summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--CHANGES.md11
-rw-r--r--Hledger/Data/Account.hs2
-rw-r--r--Hledger/Data/Amount.hs3
-rw-r--r--Hledger/Data/Commodity.hs2
-rw-r--r--Hledger/Data/Dates.hs93
-rw-r--r--Hledger/Data/Journal.hs669
-rw-r--r--Hledger/Data/Ledger.hs19
-rw-r--r--Hledger/Data/MarketPrice.hs2
-rw-r--r--Hledger/Data/PeriodicTransaction.hs1
-rw-r--r--Hledger/Data/Posting.hs60
-rw-r--r--Hledger/Data/RawOptions.hs2
-rw-r--r--Hledger/Data/StringFormat.hs4
-rw-r--r--Hledger/Data/Timeclock.hs1
-rw-r--r--Hledger/Data/Transaction.hs995
-rw-r--r--Hledger/Data/TransactionModifier.hs2
-rw-r--r--Hledger/Data/Types.hs76
-rw-r--r--Hledger/Read/Common.hs10
-rw-r--r--Hledger/Reports/BudgetReport.hs2
-rw-r--r--Hledger/Reports/PostingsReport.hs6
-rw-r--r--Hledger/Utils.hs1
-rw-r--r--hledger-lib.cabal6
-rw-r--r--hledger_csv.52
-rw-r--r--hledger_csv.info2
-rw-r--r--hledger_csv.txt2
-rw-r--r--hledger_journal.5104
-rw-r--r--hledger_journal.info222
-rw-r--r--hledger_journal.txt427
-rw-r--r--hledger_timeclock.52
-rw-r--r--hledger_timeclock.info2
-rw-r--r--hledger_timeclock.txt2
-rw-r--r--hledger_timedot.52
-rw-r--r--hledger_timedot.info2
-rw-r--r--hledger_timedot.txt2
33 files changed, 1484 insertions, 1254 deletions
diff --git a/CHANGES.md b/CHANGES.md
index d8dbc50..59d0072 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -1,6 +1,17 @@
Internal/api/developer-ish changes in the hledger-lib (and hledger) packages.
For user-visible changes, see the hledger package changelog.
+# 1.14 2019-03-01
+
+- added:
+ transaction, [v]post*, balassert* constructors, for tests etc.
+
+- renamed:
+ porigin -> poriginal
+
+- refactored:
+ transaction balancing & balance assertion checking (#438)
+
# 1.13.1 (2019/02/02)
- stop depending on here to avoid haskell-src-meta/stackage blockage.
diff --git a/Hledger/Data/Account.hs b/Hledger/Data/Account.hs
index ca36253..316d928 100644
--- a/Hledger/Data/Account.hs
+++ b/Hledger/Data/Account.hs
@@ -242,7 +242,7 @@ sortAccountTreeByDeclaration :: Account -> Account
sortAccountTreeByDeclaration a
| null $ asubs a = a
| otherwise = a{asubs=
- sortBy (comparing accountDeclarationOrderAndName) $
+ sortOn accountDeclarationOrderAndName $
map sortAccountTreeByDeclaration $ asubs a
}
diff --git a/Hledger/Data/Amount.hs b/Hledger/Data/Amount.hs
index 2906c85..370b538 100644
--- a/Hledger/Data/Amount.hs
+++ b/Hledger/Data/Amount.hs
@@ -132,7 +132,6 @@ import Data.List
import Data.Map (findWithDefault)
import Data.Maybe
import Data.Time.Calendar (Day)
-import Data.Ord (comparing)
-- import Data.Text (Text)
import qualified Data.Text as T
import Safe (maximumDef)
@@ -469,7 +468,7 @@ commodityValue j valuationdate c
where
dbg = dbg8 ("using market price for "++T.unpack c)
applicableprices =
- [p | p <- sortBy (comparing mpdate) $ jmarketprices j
+ [p | p <- sortOn mpdate $ jmarketprices j
, mpcommodity p == c
, mpdate p <= valuationdate
]
diff --git a/Hledger/Data/Commodity.hs b/Hledger/Data/Commodity.hs
index 4e095c7..1cd892c 100644
--- a/Hledger/Data/Commodity.hs
+++ b/Hledger/Data/Commodity.hs
@@ -26,7 +26,7 @@ import Hledger.Utils
-- characters that may not be used in a non-quoted commodity symbol
-nonsimplecommoditychars = "0123456789-+.@*;\n \"{}=" :: [Char]
+nonsimplecommoditychars = "0123456789-+.@*;\n \"{}=" :: String
isNonsimpleCommodityChar :: Char -> Bool
isNonsimpleCommodityChar c = isDigit c || c `textElem` otherChars
diff --git a/Hledger/Data/Dates.hs b/Hledger/Data/Dates.hs
index ef31f4c..d827431 100644
--- a/Hledger/Data/Dates.hs
+++ b/Hledger/Data/Dates.hs
@@ -126,21 +126,15 @@ showDateSpanMonthAbbrev = showPeriodMonthAbbrev . dateSpanAsPeriod
-- | Get the current local date.
getCurrentDay :: IO Day
-getCurrentDay = do
- t <- getZonedTime
- return $ localDay (zonedTimeToLocalTime t)
+getCurrentDay = localDay . zonedTimeToLocalTime <$> getZonedTime
-- | Get the current local month number.
getCurrentMonth :: IO Int
-getCurrentMonth = do
- (_,m,_) <- toGregorian `fmap` getCurrentDay
- return m
+getCurrentMonth = second3 . toGregorian <$> getCurrentDay
-- | Get the current local year.
getCurrentYear :: IO Integer
-getCurrentYear = do
- (y,_,_) <- toGregorian `fmap` getCurrentDay
- return y
+getCurrentYear = first3 . toGregorian <$> getCurrentDay
elapsedSeconds :: Fractional a => UTCTime -> UTCTime -> a
elapsedSeconds t1 = realToFrac . diffUTCTime t1
@@ -380,14 +374,13 @@ spanFromSmartDate refdate sdate = DateSpan (Just b) (Just e)
-- | Convert a smart date string to an explicit yyyy\/mm\/dd string using
-- the provided reference date, or raise an error.
fixSmartDateStr :: Day -> Text -> String
-fixSmartDateStr d s = either
- (\e->error' $ printf "could not parse date %s %s" (show s) (show e))
- id
- $ (fixSmartDateStrEither d s :: Either (ParseErrorBundle Text CustomErr) String)
+fixSmartDateStr d s =
+ either (error' . printf "could not parse date %s %s" (show s) . show) id $
+ (fixSmartDateStrEither d s :: Either (ParseErrorBundle Text CustomErr) String)
-- | A safe version of fixSmartDateStr.
fixSmartDateStrEither :: Day -> Text -> Either (ParseErrorBundle Text CustomErr) String
-fixSmartDateStrEither d = either Left (Right . showDate) . fixSmartDateStrEither' d
+fixSmartDateStrEither d = fmap showDate . fixSmartDateStrEither' d
fixSmartDateStrEither'
:: Day -> Text -> Either (ParseErrorBundle Text CustomErr) Day
@@ -469,34 +462,34 @@ fixSmartDateStrEither' d s = case parsewith smartdateonly (T.toLower s) of
-- "2009/01/01"
--
fixSmartDate :: Day -> SmartDate -> Day
-fixSmartDate refdate sdate = fix sdate
- where
- fix :: SmartDate -> Day
- fix ("","","today") = fromGregorian ry rm rd
- fix ("","this","day") = fromGregorian ry rm rd
- fix ("","","yesterday") = prevday refdate
- fix ("","last","day") = prevday refdate
- fix ("","","tomorrow") = nextday refdate
- fix ("","next","day") = nextday refdate
- fix ("","last","week") = prevweek refdate
- fix ("","this","week") = thisweek refdate
- fix ("","next","week") = nextweek refdate
- fix ("","last","month") = prevmonth refdate
- fix ("","this","month") = thismonth refdate
- fix ("","next","month") = nextmonth refdate
- fix ("","last","quarter") = prevquarter refdate
- fix ("","this","quarter") = thisquarter refdate
- fix ("","next","quarter") = nextquarter refdate
- fix ("","last","year") = prevyear refdate
- fix ("","this","year") = thisyear refdate
- fix ("","next","year") = nextyear refdate
- fix ("","",d) = fromGregorian ry rm (read d)
- fix ("",m,"") = fromGregorian ry (read m) 1
- fix ("",m,d) = fromGregorian ry (read m) (read d)
- fix (y,"","") = fromGregorian (read y) 1 1
- fix (y,m,"") = fromGregorian (read y) (read m) 1
- fix (y,m,d) = fromGregorian (read y) (read m) (read d)
- (ry,rm,rd) = toGregorian refdate
+fixSmartDate refdate = fix
+ where
+ fix :: SmartDate -> Day
+ fix ("", "", "today") = fromGregorian ry rm rd
+ fix ("", "this", "day") = fromGregorian ry rm rd
+ fix ("", "", "yesterday") = prevday refdate
+ fix ("", "last", "day") = prevday refdate
+ fix ("", "", "tomorrow") = nextday refdate
+ fix ("", "next", "day") = nextday refdate
+ fix ("", "last", "week") = prevweek refdate
+ fix ("", "this", "week") = thisweek refdate
+ fix ("", "next", "week") = nextweek refdate
+ fix ("", "last", "month") = prevmonth refdate
+ fix ("", "this", "month") = thismonth refdate
+ fix ("", "next", "month") = nextmonth refdate
+ fix ("", "last", "quarter") = prevquarter refdate
+ fix ("", "this", "quarter") = thisquarter refdate
+ fix ("", "next", "quarter") = nextquarter refdate
+ fix ("", "last", "year") = prevyear refdate
+ fix ("", "this", "year") = thisyear refdate
+ fix ("", "next", "year") = nextyear refdate
+ fix ("", "", d) = fromGregorian ry rm (read d)
+ fix ("", m, "") = fromGregorian ry (read m) 1
+ fix ("", m, d) = fromGregorian ry (read m) (read d)
+ fix (y, "", "") = fromGregorian (read y) 1 1
+ fix (y, m, "") = fromGregorian (read y) (read m) 1
+ fix (y, m, d) = fromGregorian (read y) (read m) (read d)
+ (ry, rm, rd) = toGregorian refdate
prevday :: Day -> Day
prevday = addDays (-1)
@@ -764,7 +757,7 @@ smartdateonly = do
eof
return d
-datesepchars :: [Char]
+datesepchars :: String
datesepchars = "/-."
datesepchar :: TextParser m Char
@@ -980,8 +973,7 @@ reportingintervalp = choice' [
return $ DayOfWeek n,
do string' "every"
skipMany spacenonewline
- n <- weekday
- return $ DayOfWeek n,
+ DayOfWeek <$> weekday,
do string' "every"
skipMany spacenonewline
n <- nth
@@ -1034,7 +1026,7 @@ reportingintervalp = choice' [
return $ intcons 1,
do string' "every"
skipMany spacenonewline
- n <- fmap read $ some digitChar
+ n <- read <$> some digitChar
skipMany spacenonewline
string' plural'
return $ intcons n
@@ -1061,8 +1053,7 @@ doubledatespanp rdate = do
b <- smartdate
skipMany spacenonewline
optional (choice [string' "to", string' "-"] >> skipMany spacenonewline)
- e <- smartdate
- return $ DateSpan (Just $ fixSmartDate rdate b) (Just $ fixSmartDate rdate e)
+ DateSpan (Just $ fixSmartDate rdate b) . Just . fixSmartDate rdate <$> smartdate
fromdatespanp :: Day -> TextParser m DateSpan
fromdatespanp rdate = do
@@ -1081,14 +1072,12 @@ fromdatespanp rdate = do
todatespanp :: Day -> TextParser m DateSpan
todatespanp rdate = do
choice [string' "to", string' "-"] >> skipMany spacenonewline
- e <- smartdate
- return $ DateSpan Nothing (Just $ fixSmartDate rdate e)
+ DateSpan Nothing . Just . fixSmartDate rdate <$> smartdate
justdatespanp :: Day -> TextParser m DateSpan
justdatespanp rdate = do
optional (string' "in" >> skipMany spacenonewline)
- d <- smartdate
- return $ spanFromSmartDate rdate d
+ spanFromSmartDate rdate <$> smartdate
-- | Make a datespan from two valid date strings parseable by parsedate
-- (or raise an error). Eg: mkdatespan \"2011/1/1\" \"2011/12/31\".
diff --git a/Hledger/Data/Journal.hs b/Hledger/Data/Journal.hs
index df436ef..5e4fa9f 100644
--- a/Hledger/Data/Journal.hs
+++ b/Hledger/Data/Journal.hs
@@ -1,8 +1,10 @@
-{-# LANGUAGE Rank2Types #-}
+{-# LANGUAGE CPP #-}
+{-# LANGUAGE LambdaCase #-}
{-# LANGUAGE NamedFieldPuns #-}
-{-# LANGUAGE StandaloneDeriving #-}
{-# LANGUAGE OverloadedStrings #-}
-{-# LANGUAGE CPP #-}
+{-# LANGUAGE Rank2Types #-}
+{-# LANGUAGE ScopedTypeVariables #-}
+{-# LANGUAGE StandaloneDeriving #-}
{-|
@@ -76,22 +78,24 @@ module Hledger.Data.Journal (
)
where
import Control.Applicative (Const(..))
-import Control.Arrow
import Control.Monad
import Control.Monad.Except
-import qualified Control.Monad.Reader as R
+import Control.Monad.Extra
+import Control.Monad.Reader as R
import Control.Monad.ST
import Data.Array.ST
+import Data.Function ((&))
import Data.Functor.Identity (Identity(..))
-import qualified Data.HashTable.ST.Cuckoo as HT
+import qualified Data.HashTable.ST.Cuckoo as H
import Data.List
import Data.List.Extra (groupSort)
+import qualified Data.Map as M
import Data.Maybe
#if !(MIN_VERSION_base(4,11,0))
import Data.Monoid
#endif
-import Data.Ord
import qualified Data.Semigroup as Sem
+import qualified Data.Set as S
import Data.Text (Text)
import qualified Data.Text as T
import Safe (headMay, headDef)
@@ -99,8 +103,6 @@ import Data.Time.Calendar
import Data.Tree
import System.Time (ClockTime(TOD))
import Text.Printf
-import qualified Data.Map as M
-import qualified Data.Set as S
import Hledger.Utils
import Hledger.Data.Types
@@ -564,280 +566,323 @@ journalUntieTransactions t@Transaction{tpostings=ps} = t{tpostings=map (\p -> p{
journalModifyTransactions :: Journal -> Journal
journalModifyTransactions j = j{ jtxns = modifyTransactions (jtxnmodifiers j) (jtxns j) }
--- | Check any balance assertions in the journal and return an error
--- message if any of them fail.
-journalCheckBalanceAssertions :: Journal -> Either String Journal
-journalCheckBalanceAssertions j =
- runST $ journalBalanceTransactionsST
- True
- j
- (return ())
- (\_ _ -> return ())
- (const $ return j)
-
--- | Check a posting's balance assertion and return an error if it
--- fails.
-checkBalanceAssertion :: Posting -> MixedAmount -> Either String ()
-checkBalanceAssertion p@Posting{pbalanceassertion=Just (BalanceAssertion{baamount,baexact})} actualbal =
- foldl' f (Right ()) assertedamts
- where
- f (Right _) assertedamt = checkBalanceAssertionCommodity p assertedamt actualbal
- f err _ = err
- assertedamts = baamount : otheramts
- where
- assertedcomm = acommodity baamount
- otheramts | baexact = map (\a -> a{ aquantity = 0 }) $ amounts $ filterMixedAmount (\a -> acommodity a /= assertedcomm) actualbal
- | otherwise = []
-checkBalanceAssertion _ _ = Right ()
-
--- | Are the asserted balance and the actual balance
--- exactly equal (disregarding display precision) ?
--- The posting is used for creating an error message.
-checkBalanceAssertionCommodity :: Posting -> Amount -> MixedAmount -> Either String ()
-checkBalanceAssertionCommodity p assertedamt actualbal
- | pass = Right ()
- | otherwise = Left err
- where
- assertedcomm = acommodity assertedamt
- actualbalincommodity = fromMaybe nullamt $ find ((== assertedcomm) . acommodity) (amounts actualbal)
- pass =
- aquantity
- -- traceWith (("asserted:"++).showAmountDebug)
- assertedamt ==
- aquantity
- -- traceWith (("actual:"++).showAmountDebug)
- actualbalincommodity
- diff = aquantity assertedamt - aquantity actualbalincommodity
- err = printf (unlines
- [ "balance assertion: %s",
- "\nassertion details:",
- "date: %s",
- "account: %s",
- "commodity: %s",
- -- "display precision: %d",
- "calculated: %s", -- (at display precision: %s)",
- "asserted: %s", -- (at display precision: %s)",
- "difference: %s"
- ])
- (case ptransaction p of
- Nothing -> "?" -- shouldn't happen
- Just t -> printf "%s\ntransaction:\n%s"
- (showGenericSourcePos pos)
- (chomp $ showTransaction t)
- :: String
- where
- pos = baposition $ fromJust $ pbalanceassertion p
- )
- (showDate $ postingDate p)
- (T.unpack $ paccount p) -- XXX pack
- assertedcomm
- -- (asprecision $ astyle actualbalincommodity) -- should be the standard display precision I think
- (show $ aquantity actualbalincommodity)
- -- (showAmount actualbalincommodity)
- (show $ aquantity assertedamt)
- -- (showAmount assertedamt)
- (show diff)
-
--- | Fill in any missing amounts and check that all journal transactions
--- balance and all balance assertions pass, or return an error message.
--- This is done after parsing all amounts and applying canonical
--- commodity styles, since balancing depends on display precision.
--- Reports only the first error encountered.
-journalBalanceTransactions :: Bool -> Journal -> Either String Journal
-journalBalanceTransactions assrt j =
- runST $ journalBalanceTransactionsST
- assrt -- check balance assertions also ?
- (journalNumberTransactions j) -- journal to process
- (newArray_ (1, genericLength $ jtxns j) :: forall s. ST s (STArray s Integer Transaction)) -- initialise state
- (\arr tx -> writeArray arr (tindex tx) tx) -- update state
- (fmap (\txns -> j{ jtxns = txns}) . getElems) -- summarise state
-
--- | Helper used by 'journalBalanceTransactions' and 'journalCheckBalanceAssertions'.
--- Balances transactions, applies balance assignments, and checks balance assertions
--- at the same time.
-journalBalanceTransactionsST ::
- Bool
- -> Journal
- -> ST s txns -- ^ initialise state
- -> (txns -> Transaction -> ST s ()) -- ^ update state
- -> (txns -> ST s a) -- ^ summarise state
- -> ST s (Either String a)
-journalBalanceTransactionsST assrt j createStore storeIn extract =
- runExceptT $ do
- bals <- lift $ HT.newSized size
- txStore <- lift $ createStore
- let env = Env bals
- (storeIn txStore)
- assrt
- (Just $ journalCommodityStyles j)
- (getModifierAccountNames j)
- flip R.runReaderT env $ do
- dated <- fmap snd . sortBy (comparing fst) . concat
- <$> mapM' discriminateByDate (jtxns j)
- mapM' checkInferAndRegisterAmounts dated
- lift $ extract txStore
- where
- size = genericLength $ journalPostings j
-
-
--- | Collect account names in account modifiers into a set
-getModifierAccountNames :: Journal -> S.Set AccountName
-getModifierAccountNames j = S.fromList $
- map paccount $
- concatMap tmpostingrules $
- jtxnmodifiers j
-
--- | Monad transformer stack with a reference to a mutable hashtable
--- of current account balances and a mutable array of finished
--- transactions in original parsing order.
-type CurrentBalancesModifier s = R.ReaderT (Env s) (ExceptT String (ST s))
-
--- | Environment for 'CurrentBalancesModifier'
-data Env s = Env { eBalances :: HT.HashTable s AccountName MixedAmount
- , eStoreTx :: Transaction -> ST s ()
- , eAssrt :: Bool
- , eStyles :: Maybe (M.Map CommoditySymbol AmountStyle)
- , eUnassignable :: S.Set AccountName
- }
-
--- | This converts a transaction into a list of transactions or
--- postings whose dates have to be considered when checking
--- balance assertions and handled by 'checkInferAndRegisterAmounts'.
---
--- Transaction without balance assignments can be balanced and stored
--- immediately and their (possibly) dated postings are returned.
---
--- Transaction with balance assignments are only supported if no
--- posting has a 'pdate' value. Supported transactions will be
--- returned unchanged and balanced and stored later in 'checkInferAndRegisterAmounts'.
-discriminateByDate :: Transaction
- -> CurrentBalancesModifier s [(Day, Either Posting Transaction)]
-discriminateByDate tx
- | null (assignmentPostings tx) = do
- styles <- R.reader $ eStyles
- balanced <- lift $ ExceptT $ return $ balanceTransaction styles tx
- storeTransaction balanced
- return $
- fmap (postingDate &&& (Left . removePrices)) $ tpostings $ balanced
- | True = do
- when (any (isJust . pdate) $ tpostings tx) $
- throwError $ unlines $
- ["postings may not have both a custom date and a balance assignment."
- ,"Write the posting amount explicitly, or remove the posting date:\n"
- , showTransaction tx]
- return
- [(tdate tx, Right $ tx { tpostings = removePrices <$> tpostings tx })]
-
--- | Throw an error if a posting is in the unassignable set.
-checkUnassignablePosting :: Posting -> CurrentBalancesModifier s ()
-checkUnassignablePosting p = do
- unassignable <- R.asks eUnassignable
- if (isAssignment p && paccount p `S.member` unassignable)
- then throwError $ unlines $
- [ "cannot assign amount to account "
- , ""
- , " " ++ (T.unpack $ paccount p)
- , ""
- , "because it is also included in transaction modifiers."
- ]
- else return ()
-
-
--- | This function takes an object describing changes to
--- account balances on a single day - either a single posting
--- (from an already balanced transaction without assignments)
--- or a whole transaction with assignments (which is required to
--- have no posting with pdate set).
---
--- For a single posting, there is not much to do. Only add its amount
--- to its account and check the assertion, if there is one. This
--- functionality is provided by 'addAmountAndCheckBalance'.
---
--- For a whole transaction, it loops over all postings, and performs
--- 'addAmountAndCheckBalance', if there is an amount. If there is no
--- amount, the amount is inferred by the assertion or left empty if
--- there is no assertion. Then, the transaction is balanced, the
--- inferred amount added to the balance (all in 'balanceTransactionUpdate')
--- and the resulting transaction with no missing amounts is stored
--- in the array, for later retrieval.
---
--- Again in short:
---
--- 'Left Posting': Check the balance assertion and update the
--- account balance. If the amount is empty do nothing. this can be
--- the case e.g. for virtual postings
---
--- 'Right Transaction': Loop over all postings, infer their amounts
--- and then balance and store the transaction.
-checkInferAndRegisterAmounts :: Either Posting Transaction
- -> CurrentBalancesModifier s ()
-checkInferAndRegisterAmounts (Left p) = do
- checkUnassignablePosting p
- void $ addAmountAndCheckBalance return p
-checkInferAndRegisterAmounts (Right oldTx) = do
- let ps = tpostings oldTx
- mapM_ checkUnassignablePosting ps
- styles <- R.reader $ eStyles
- newPostings <- forM ps $ addAmountAndCheckBalance inferFromAssignment
- storeTransaction =<< balanceTransactionUpdate
- (fmap void . addToBalance) styles oldTx { tpostings = newPostings }
- where
- inferFromAssignment :: Posting -> CurrentBalancesModifier s Posting
- inferFromAssignment p = do
- let acc = paccount p
- case pbalanceassertion p of
- Just ba | baexact ba -> do
- diff <- setMixedBalance acc $ Mixed [baamount ba]
- fullPosting diff p
- Just ba | otherwise -> do
- old <- liftModifier $ \Env{ eBalances = bals } -> HT.lookup bals acc
- let amt = baamount ba
- assertedcomm = acommodity amt
- diff <- setMixedBalance acc $
- Mixed [amt] + filterMixedAmount (\a -> acommodity a /= assertedcomm) (fromMaybe nullmixedamt old)
- fullPosting diff p
- Nothing -> return p
- fullPosting amt p = return p
- { pamount = amt
- , porigin = Just $ originalPosting p
- }
+-- | Check any balance assertions in the journal and return an error message
+-- if any of them fail (or if the transaction balancing they require fails).
+journalCheckBalanceAssertions :: Journal -> Maybe String
+journalCheckBalanceAssertions = either Just (const Nothing) . journalBalanceTransactions True
+
+-- "Transaction balancing" - inferring missing amounts and checking transaction balancedness and balance assertions
+
+-- | Monad used for statefully balancing/amount-inferring/assertion-checking
+-- a sequence of transactions.
+-- Perhaps can be simplified, or would a different ordering of layers make sense ?
+-- If you see a way, let us know.
+type Balancing s = ReaderT (BalancingState s) (ExceptT String (ST s))
+
+-- | The state used while balancing a sequence of transactions.
+data BalancingState s = BalancingState {
+ -- read only
+ bsStyles :: Maybe (M.Map CommoditySymbol AmountStyle) -- ^ commodity display styles
+ ,bsUnassignable :: S.Set AccountName -- ^ accounts in which balance assignments may not be used
+ ,bsAssrt :: Bool -- ^ whether to check balance assertions
+ -- mutable
+ ,bsBalances :: H.HashTable s AccountName MixedAmount -- ^ running account balances, initially empty
+ ,bsTransactions :: STArray s Integer Transaction -- ^ the transactions being balanced
+ }
--- | Adds a posting's amount to the posting's account balance and
--- checks a possible balance assertion. Or if there is no amount,
--- runs the supplied fallback action.
-addAmountAndCheckBalance ::
- (Posting -> CurrentBalancesModifier s Posting) -- ^ action if posting has no amount
- -> Posting
- -> CurrentBalancesModifier s Posting
-addAmountAndCheckBalance _ p | hasAmount p = do
- newAmt <- addToBalance (paccount p) $ pamount p
- assrt <- R.reader eAssrt
- lift $ when assrt $ ExceptT $ return $ checkBalanceAssertion p newAmt
- return p
-addAmountAndCheckBalance fallback p = fallback p
-
--- | Sets all commodities comprising an account's balance to the given
--- amounts and returns the difference from the previous balance.
-setMixedBalance :: AccountName -> MixedAmount -> CurrentBalancesModifier s MixedAmount
-setMixedBalance acc amt = liftModifier $ \Env{ eBalances = bals } -> do
- old <- HT.lookup bals acc
- HT.insert bals acc amt
- return $ maybe amt (amt -) old
-
--- | Adds an amount to an account's balance and returns the resulting balance.
-addToBalance :: AccountName -> MixedAmount -> CurrentBalancesModifier s MixedAmount
-addToBalance acc amt = liftModifier $ \Env{ eBalances = bals } -> do
- new <- maybe amt (+ amt) <$> HT.lookup bals acc
- HT.insert bals acc new
+-- | Access the current balancing state, and possibly modify the mutable bits,
+-- lifting through the Except and Reader layers into the Balancing monad.
+withB :: (BalancingState s -> ST s a) -> Balancing s a
+withB f = ask >>= lift . lift . f
+
+-- | Get an account's running balance so far.
+getAmountB :: AccountName -> Balancing s MixedAmount
+getAmountB acc = withB $ \BalancingState{bsBalances} -> do
+ fromMaybe 0 <$> H.lookup bsBalances acc
+
+-- | Add an amount to an account's running balance, and return the new running balance.
+addAmountB :: AccountName -> MixedAmount -> Balancing s MixedAmount
+addAmountB acc amt = withB $ \BalancingState{bsBalances} -> do
+ old <- fromMaybe 0 <$> H.lookup bsBalances acc
+ let new = old + amt
+ H.insert bsBalances acc new
return new
--- | Stores a transaction in the transaction array in original parsing order.
-storeTransaction :: Transaction -> CurrentBalancesModifier s ()
-storeTransaction tx = liftModifier $ ($tx) . eStoreTx
+-- | Set an account's running balance to this amount, and return the difference from the old.
+setAmountB :: AccountName -> MixedAmount -> Balancing s MixedAmount
+setAmountB acc amt = withB $ \BalancingState{bsBalances} -> do
+ old <- fromMaybe 0 <$> H.lookup bsBalances acc
+ H.insert bsBalances acc amt
+ return $ amt - old
+
+-- | Update (overwrite) this transaction with a new one.
+storeTransactionB :: Transaction -> Balancing s ()
+storeTransactionB t = withB $ \BalancingState{bsTransactions} ->
+ void $ writeArray bsTransactions (tindex t) t
+
+-- | Infer any missing amounts (to satisfy balance assignments and
+-- to balance transactions) and check that all transactions balance
+-- and (optional) all balance assertions pass. Or return an error message
+-- (just the first error encountered).
+--
+-- Assumes journalInferCommodityStyles has been called, since those affect transaction balancing.
+--
+-- This does multiple things because amount inferring, balance assignments,
+-- balance assertions and posting dates are interdependent.
+--
+-- This can be simplified further. Overview as of 20190219:
+-- @
+-- ****** parseAndFinaliseJournal['] (Cli/Utils.hs), journalAddForecast (Common.hs), budgetJournal (BudgetReport.hs), tests (BalanceReport.hs)
+-- ******* journalBalanceTransactions
+-- ******** runST
+-- ********* runExceptT
+-- ********** balanceTransaction (Transaction.hs)
+-- *********** balanceTransactionHelper
+-- ********** runReaderT
+-- *********** balanceTransactionAndCheckAssertionsB
+-- ************ addAmountAndCheckAssertionB
+-- ************ addOrAssignAmountAndCheckAssertionB
+-- ************ balanceTransactionHelper (Transaction.hs)
+-- ****** uiCheckBalanceAssertions d ui@UIState{aopts=UIOpts{cliopts_=copts}, ajournal=j} (ErrorScreen.hs)
+-- ******* journalCheckBalanceAssertions
+-- ******** journalBalanceTransactions
+-- ****** transactionWizard, postingsBalanced (Add.hs), tests (Transaction.hs)
+-- ******* balanceTransaction (Transaction.hs) XXX hledger add won't allow balance assignments + missing amount ?
+-- @
+journalBalanceTransactions :: Bool -> Journal -> Either String Journal
+journalBalanceTransactions assrt j' =
+ let
+ -- ensure transactions are numbered, so we can store them by number
+ j@Journal{jtxns=ts} = journalNumberTransactions j'
+ -- display precisions used in balanced checking
+ styles = Just $ journalCommodityStyles j
+ -- balance assignments will not be allowed on these
+ txnmodifieraccts = S.fromList $ map paccount $ concatMap tmpostingrules $ jtxnmodifiers j
+ in
+ runST $ do
+ -- We'll update a mutable array of transactions as we balance them,
+ -- not strictly necessary but avoids a sort at the end I think.
+ balancedtxns <- newListArray (1, genericLength ts) ts
+
+ -- Infer missing posting amounts, check transactions are balanced,
+ -- and check balance assertions. This is done in two passes:
+ runExceptT $ do
+
+ -- 1. Step through the transactions, balancing the ones which don't have balance assignments
+ -- and leaving the others for later. The balanced ones are split into their postings.
+ -- The postings and not-yet-balanced transactions remain in the same relative order.
+ psandts :: [Either Posting Transaction] <- fmap concat $ forM ts $ \case
+ t | null $ assignmentPostings t -> case balanceTransaction styles t of
+ Left e -> throwError e
+ Right t' -> do
+ lift $ writeArray balancedtxns (tindex t') t'
+ return $ map Left $ tpostings t'
+ t -> return [Right t]
+
+ -- 2. Sort these items by date, preserving the order of same-day items,
+ -- and step through them while keeping running account balances,
+ runningbals <- lift $ H.newSized (length $ journalAccountNamesUsed j)
+ flip runReaderT (BalancingState styles txnmodifieraccts assrt runningbals balancedtxns) $ do
+ -- performing balance assignments in, and balancing, the remaining transactions,
+ -- and checking balance assertions as each posting is processed.
+ void $ mapM' balanceTransactionAndCheckAssertionsB $ sortOn (either postingDate tdate) psandts
+
+ ts' <- lift $ getElems balancedtxns
+ return j{jtxns=ts'}
+
+-- | This function is called statefully on each of a date-ordered sequence of
+-- 1. fully explicit postings from already-balanced transactions and
+-- 2. not-yet-balanced transactions containing balance assignments.
+-- It executes balance assignments and finishes balancing the transactions,
+-- and checks balance assertions on each posting as it goes.
+-- An error will be thrown if a transaction can't be balanced
+-- or if an illegal balance assignment is found (cf checkIllegalBalanceAssignment).
+-- Transaction prices are removed, which helps eg balance-assertions.test: 15. Mix different commodities and assignments.
+-- This stores the balanced transactions in case 2 but not in case 1.
+balanceTransactionAndCheckAssertionsB :: Either Posting Transaction -> Balancing s ()
+
+balanceTransactionAndCheckAssertionsB (Left p@Posting{}) =
+ -- update the account's running balance and check the balance assertion if any
+ void $ addAmountAndCheckAssertionB $ removePrices p
+
+balanceTransactionAndCheckAssertionsB (Right t@Transaction{tpostings=ps}) = do
+ -- make sure we can handle the balance assignments
+ mapM_ checkIllegalBalanceAssignmentB ps
+ -- for each posting, infer its amount from the balance assignment if applicable,
+ -- update the account's running balance and check the balance assertion if any
+ ps' <- forM ps $ \p -> pure (removePrices p) >>= addOrAssignAmountAndCheckAssertionB
+ -- infer any remaining missing amounts, and make sure the transaction is now fully balanced
+ styles <- R.reader bsStyles
+ case balanceTransactionHelper styles t{tpostings=ps'} of
+ Left err -> throwError err
+ Right (t', inferredacctsandamts) -> do
+ -- for each amount just inferred, update the running balance
+ mapM_ (uncurry addAmountB) inferredacctsandamts
+ -- and save the balanced transaction.
+ storeTransactionB t'
+
+-- | If this posting has an explicit amount, add it to the account's running balance.
+-- If it has a missing amount and a balance assignment, infer the amount from, and
+-- reset the running balance to, the assigned balance.
+-- If it has a missing amount and no balance assignment, leave it for later.
+-- Then test the balance assertion if any.
+addOrAssignAmountAndCheckAssertionB :: Posting -> Balancing s Posting
+addOrAssignAmountAndCheckAssertionB p@Posting{paccount=acc, pamount=amt, pbalanceassertion=mba}
+ | hasAmount p = do
+ newbal <- addAmountB acc amt
+ whenM (R.reader bsAssrt) $ checkBalanceAssertionB p newbal
+ return p
+ | Just BalanceAssertion{baamount,batotal} <- mba = do
+ (diff,newbal) <- case batotal of
+ True -> do
+ -- a total balance assignment
+ let newbal = Mixed [baamount]
+ diff <- setAmountB acc newbal
+ return (diff,newbal)
+ False -> do
+ -- a partial balance assignment
+ oldbalothercommodities <- filterMixedAmount ((acommodity baamount /=) . acommodity) <$> getAmountB acc
+ let assignedbalthiscommodity = Mixed [baamount]
+ newbal = oldbalothercommodities + assignedbalthiscommodity
+ diff <- setAmountB acc newbal
+ return (diff,newbal)
+ let p' = p{pamount=diff, poriginal=Just $ originalPosting p}
+ whenM (R.reader bsAssrt) $ checkBalanceAssertionB p' newbal
+ return p'
+ -- no amount, no balance assertion (GHC 7 doesn't like Nothing <- mba here)
+ | otherwise = return p
+
+-- | Add the posting's amount to its account's running balance, and
+-- optionally check the posting's balance assertion if any.
+-- The posting is expected to have an explicit amount (otherwise this does nothing).
+-- Adding and checking balance assertions are tightly paired because we
+-- need to see the balance as it stands after each individual posting.
+addAmountAndCheckAssertionB :: Posting -> Balancing s Posting
+addAmountAndCheckAssertionB p | hasAmount p = do
+ newbal <- addAmountB (paccount p) (pamount p)
+ whenM (R.reader bsAssrt) $ checkBalanceAssertionB p newbal
+ return p
+addAmountAndCheckAssertionB p = return p
+
+-- | Check a posting's balance assertion against the given actual balance, and
+-- return an error if the assertion is not satisfied.
+-- If the assertion is partial, unasserted commodities in the actual balance
+-- are ignored; if it is total, they will cause the assertion to fail.
+checkBalanceAssertionB :: Posting -> MixedAmount -> Balancing s ()
+checkBalanceAssertionB p@Posting{pbalanceassertion=Just (BalanceAssertion{baamount,batotal})} actualbal =
+ forM_ assertedamts $ \amt -> checkBalanceAssertionOneCommodityB p amt actualbal
+ where
+ assertedamts = baamount : otheramts
+ where
+ assertedcomm = acommodity baamount
+ otheramts | batotal = map (\a -> a{aquantity=0}) $ amounts $ filterMixedAmount ((/=assertedcomm).acommodity) actualbal
+ | otherwise = []
+checkBalanceAssertionB _ _ = return ()
+
+-- | Does this (single commodity) expected balance match the amount of that
+-- commodity in the given (multicommodity) actual balance ? If not, returns a
+-- balance assertion failure message based on the provided posting. To match,
+-- the amounts must be exactly equal (display precision is ignored here).
+-- If the assertion is inclusive, the expected amount is compared with the account's
+-- subaccount-inclusive balance; otherwise, with the subaccount-exclusive balance.
+checkBalanceAssertionOneCommodityB :: Posting -> Amount -> MixedAmount -> Balancing s ()
+checkBalanceAssertionOneCommodityB p@Posting{paccount=assertedacct} assertedamt actualbal = do
+ let isinclusive = maybe False bainclusive $ pbalanceassertion p
+ actualbal' <-
+ if isinclusive
+ then
+ -- sum the running balances of this account and any of its subaccounts seen so far
+ withB $ \BalancingState{bsBalances} ->
+ H.foldM
+ (\ibal (acc, amt) -> return $ ibal +
+ if assertedacct==acc || assertedacct `isAccountNamePrefixOf` acc then amt else 0)
+ 0
+ bsBalances
+ else return actualbal
+ let
+ assertedcomm = acommodity assertedamt
+ actualbalincomm = headDef 0 $ amounts $ filterMixedAmountByCommodity assertedcomm $ actualbal'
+ pass =
+ aquantity
+ -- traceWith (("asserted:"++).showAmountDebug)
+ assertedamt ==
+ aquantity
+ -- traceWith (("actual:"++).showAmountDebug)
+ actualbalincomm
+
+ errmsg = printf (unlines
+ [ "balance assertion: %s",
+ "\nassertion details:",
+ "date: %s",
+ "account: %s%s",
+ "commodity: %s",
+ -- "display precision: %d",
+ "calculated: %s", -- (at display precision: %s)",
+ "asserted: %s", -- (at display precision: %s)",
+ "difference: %s"
+ ])
+ (case ptransaction p of
+ Nothing -> "?" -- shouldn't happen
+ Just t -> printf "%s\ntransaction:\n%s"
+ (showGenericSourcePos pos)
+ (chomp $ showTransaction t)
+ :: String
+ where
+ pos = baposition $ fromJust $ pbalanceassertion p
+ )
+ (showDate $ postingDate p)
+ (T.unpack $ paccount p) -- XXX pack
+ (if isinclusive then " (and subs)" else "" :: String)
+ assertedcomm
+ -- (asprecision $ astyle actualbalincommodity) -- should be the standard display precision I think
+ (show $ aquantity actualbalincomm)
+ -- (showAmount actualbalincommodity)
+ (show $ aquantity assertedamt)
+ -- (showAmount assertedamt)
+ (show $ aquantity assertedamt - aquantity actualbalincomm)
+
+ when (not pass) $ throwError errmsg
+
+-- | Throw an error if this posting is trying to do an illegal balance assignment.
+checkIllegalBalanceAssignmentB :: Posting -> Balancing s ()
+checkIllegalBalanceAssignmentB p = do
+ checkBalanceAssignmentPostingDateB p
+ checkBalanceAssignmentUnassignableAccountB p
+
+-- XXX these should show position. annotateErrorWithTransaction t ?
+
+-- | Throw an error if this posting is trying to do a balance assignment and
+-- has a custom posting date (which makes amount inference too hard/impossible).
+checkBalanceAssignmentPostingDateB :: Posting -> Balancing s ()
+checkBalanceAssignmentPostingDateB p =
+ when (hasBalanceAssignment p && isJust (pdate p)) $
+ throwError $ unlines $
+ ["postings which are balance assignments may not have a custom date."
+ ,"Please write the posting amount explicitly, or remove the posting date:"
+ ,""
+ ,maybe (unlines $ showPostingLines p) showTransaction $ ptransaction p
+ ]
+
+-- | Throw an error if this posting is trying to do a balance assignment and
+-- the account does not allow balance assignments (eg because it is referenced
+-- by a transaction modifier, which might generate additional postings to it).
+checkBalanceAssignmentUnassignableAccountB :: Posting -> Balancing s ()
+checkBalanceAssignmentUnassignableAccountB p = do
+ unassignable <- R.asks bsUnassignable
+ when (hasBalanceAssignment p && paccount p `S.member` unassignable) $
+ throwError $ unlines $
+ ["balance assignments cannot be used with accounts which are"
+ ,"posted to by transaction modifier rules (auto postings)."
+ ,"Please write the posting amount explicitly, or remove the rule."
+ ,""
+ ,"account: "++T.unpack (paccount p)
+ ,""
+ ,"transaction:"
+ ,""
+ ,maybe (unlines $ showPostingLines p) showTransaction $ ptransaction p
+ ]
--- | Helper function.
-liftModifier :: (Env s -> ST s a) -> CurrentBalancesModifier s a
-liftModifier f = R.ask >>= lift . lift . f
+--
-- | Choose and apply a consistent display format to the posting
-- amounts in each commodity. Each commodity's format is specified by
@@ -884,13 +929,12 @@ commodityStylesFromAmounts amts = M.fromList commstyles
-- That is: the style of the first, and the maximum precision of all.
canonicalStyleFrom :: [AmountStyle] -> AmountStyle
canonicalStyleFrom [] = amountstyle
-canonicalStyleFrom ss@(first:_) =
- first{asprecision=prec, asdecimalpoint=mdec, asdigitgroups=mgrps}
+canonicalStyleFrom ss@(first:_) = first {asprecision = prec, asdecimalpoint = mdec, asdigitgroups = mgrps}
where
- mgrps = maybe Nothing Just $ headMay $ catMaybes $ map asdigitgroups ss
+ mgrps = headMay $ mapMaybe asdigitgroups ss
-- precision is maximum of all precisions
prec = maximumStrict $ map asprecision ss
- mdec = Just $ headDef '.' $ catMaybes $ map asdecimalpoint ss
+ mdec = Just $ headDef '.' $ mapMaybe asdecimalpoint ss
-- precision is that of first amount with a decimal point
-- (mdec, prec) =
-- case filter (isJust . asdecimalpoint) ss of
@@ -993,7 +1037,7 @@ journalDateSpan secondary j
latest = maximumStrict dates
dates = pdates ++ tdates
tdates = map (if secondary then transactionDate2 else tdate) ts
- pdates = concatMap (catMaybes . map (if secondary then (Just . postingDate2) else pdate) . tpostings) ts
+ pdates = concatMap (mapMaybe (if secondary then (Just . postingDate2) else pdate) . tpostings) ts
ts = jtxns j
-- | Apply the pivot transformation to all postings in a journal,
@@ -1009,7 +1053,7 @@ transactionPivot fieldortagname t = t{tpostings = map (postingPivot fieldortagna
-- | Replace this posting's account name with the value
-- of the given field or tag, if any, otherwise the empty string.
postingPivot :: Text -> Posting -> Posting
-postingPivot fieldortagname p = p{paccount = pivotedacct, porigin = Just $ originalPosting p}
+postingPivot fieldortagname p = p{paccount = pivotedacct, poriginal = Just $ originalPosting p}
where
pivotedacct
| Just t <- ptransaction p, fieldortagname == "code" = tcode t
@@ -1207,4 +1251,59 @@ tests_Journal = tests "Journal" [
,test "expenses" $ expectEq (namesfrom journalExpenseAccountQuery) ["expenses","expenses:food","expenses:supplies"]
]
+ ,tests "journalBalanceTransactions" [
+
+ test "balance-assignment" $ do
+ let ej = journalBalanceTransactions True $
+ --2019/01/01
+ -- (a) = 1
+ nulljournal{ jtxns = [
+ transaction "2019/01/01" [ vpost' "a" missingamt (balassert (num 1)) ]
+ ]}
+ expectRight ej
+ let Right j = ej
+ (jtxns j & head & tpostings & head & pamount) `is` Mixed [num 1]
+
+ ,test "same-day-1" $ do
+ expectRight $ journalBalanceTransactions True $
+ --2019/01/01
+ -- (a) = 1
+ --2019/01/01
+ -- (a) 1 = 2
+ nulljournal{ jtxns = [
+ transaction "2019/01/01" [ vpost' "a" missingamt (balassert (num 1)) ]
+ ,transaction "2019/01/01" [ vpost' "a" (num 1) (balassert (num 2)) ]
+ ]}
+
+ ,test "same-day-2" $ do
+ expectRight $ journalBalanceTransactions True $
+ --2019/01/01
+ -- (a) 2 = 2
+ --2019/01/01
+ -- b 1
+ -- a
+ --2019/01/01
+ -- a 0 = 1
+ nulljournal{ jtxns = [
+ transaction "2019/01/01" [ vpost' "a" (num 2) (balassert (num 2)) ]
+ ,transaction "2019/01/01" [
+ post' "b" (num 1) Nothing
+ ,post' "a" missingamt Nothing
+ ]
+ ,transaction "2019/01/01" [ post' "a" (num 0) (balassert (num 1)) ]
+ ]}
+
+ ,test "out-of-order" $ do
+ expectRight $ journalBalanceTransactions True $
+ --2019/1/2
+ -- (a) 1 = 2
+ --2019/1/1
+ -- (a) 1 = 1
+ nulljournal{ jtxns = [
+ transaction "2019/01/02" [ vpost' "a" (num 1) (balassert (num 2)) ]
+ ,transaction "2019/01/01" [ vpost' "a" (num 1) (balassert (num 1)) ]
+ ]}
+
+ ]
+
]
diff --git a/Hledger/Data/Ledger.hs b/Hledger/Data/Ledger.hs
index b6d963a..0834554 100644
--- a/Hledger/Data/Ledger.hs
+++ b/Hledger/Data/Ledger.hs
@@ -107,12 +107,13 @@ ledgerCommodities = M.keys . jinferredcommodities . ljournal
-- tests
-tests_Ledger = tests "Ledger" [
-
- tests "ledgerFromJournal" [
- (length $ ledgerPostings $ ledgerFromJournal Any nulljournal) `is` 0
- ,(length $ ledgerPostings $ ledgerFromJournal Any samplejournal) `is` 13
- ,(length $ ledgerPostings $ ledgerFromJournal (Depth 2) samplejournal) `is` 7
- ]
-
- ]
+tests_Ledger =
+ tests
+ "Ledger"
+ [ tests
+ "ledgerFromJournal"
+ [ length (ledgerPostings $ ledgerFromJournal Any nulljournal) `is` 0
+ , length (ledgerPostings $ ledgerFromJournal Any samplejournal) `is` 13
+ , length (ledgerPostings $ ledgerFromJournal (Depth 2) samplejournal) `is` 7
+ ]
+ ]
diff --git a/Hledger/Data/MarketPrice.hs b/Hledger/Data/MarketPrice.hs
index a06a161..cf99446 100644
--- a/Hledger/Data/MarketPrice.hs
+++ b/Hledger/Data/MarketPrice.hs
@@ -8,8 +8,6 @@ value of things at a given date.
-}
-{-# LANGUAGE OverloadedStrings, LambdaCase #-}
-
module Hledger.Data.MarketPrice
where
import qualified Data.Text as T
diff --git a/Hledger/Data/PeriodicTransaction.hs b/Hledger/Data/PeriodicTransaction.hs
index ec788c1..a2b71ee 100644
--- a/Hledger/Data/PeriodicTransaction.hs
+++ b/Hledger/Data/PeriodicTransaction.hs
@@ -1,7 +1,6 @@
{-# LANGUAGE CPP #-}
{-# LANGUAGE OverloadedStrings #-}
{-# LANGUAGE RecordWildCards #-}
-{-# LANGUAGE StandaloneDeriving #-}
{-|
A 'PeriodicTransaction' is a rule describing recurring transactions.
diff --git a/Hledger/Data/Posting.hs b/Hledger/Data/Posting.hs
index 48921c8..9d4b8c0 100644
--- a/Hledger/Data/Posting.hs
+++ b/Hledger/Data/Posting.hs
@@ -15,9 +15,16 @@ module Hledger.Data.Posting (
nullposting,
posting,
post,
+ vpost,
+ post',
+ vpost',
nullsourcepos,
nullassertion,
assertion,
+ balassert,
+ balassertTot,
+ balassertParInc,
+ balassertTotInc,
-- * operations
originalPosting,
postingStatus,
@@ -25,7 +32,7 @@ module Hledger.Data.Posting (
isVirtual,
isBalancedVirtual,
isEmptyPosting,
- isAssignment,
+ hasBalanceAssignment,
hasAmount,
postingAllTags,
transactionAllTags,
@@ -66,7 +73,6 @@ import Data.MemoUgly (memo)
#if !(MIN_VERSION_base(4,11,0))
import Data.Monoid
#endif
-import Data.Ord
import Data.Text (Text)
import qualified Data.Text as T
import Data.Time.Calendar
@@ -92,12 +98,27 @@ nullposting = Posting
,ptags=[]
,pbalanceassertion=Nothing
,ptransaction=Nothing
- ,porigin=Nothing
+ ,poriginal=Nothing
}
posting = nullposting
+-- constructors
+
+-- | Make a posting to an account.
post :: AccountName -> Amount -> Posting
-post acct amt = posting {paccount=acct, pamount=Mixed [amt]}
+post acc amt = posting {paccount=acc, pamount=Mixed [amt]}
+
+-- | Make a virtual (unbalanced) posting to an account.
+vpost :: AccountName -> Amount -> Posting
+vpost acc amt = (post acc amt){ptype=VirtualPosting}
+
+-- | Make a posting to an account, maybe with a balance assertion.
+post' :: AccountName -> Amount -> Maybe BalanceAssertion -> Posting
+post' acc amt ass = posting {paccount=acc, pamount=Mixed [amt], pbalanceassertion=ass}
+
+-- | Make a virtual (unbalanced) posting to an account, maybe with a balance assertion.
+vpost' :: AccountName -> Amount -> Maybe BalanceAssertion -> Posting
+vpost' acc amt ass = (post' acc amt ass){ptype=VirtualPosting, pbalanceassertion=ass}
nullsourcepos :: GenericSourcePos
nullsourcepos = JournalSourcePos "" (1,1)
@@ -105,14 +126,31 @@ nullsourcepos = JournalSourcePos "" (1,1)
nullassertion, assertion :: BalanceAssertion
nullassertion = BalanceAssertion
{baamount=nullamt
- ,baexact=False
+ ,batotal=False
+ ,bainclusive=False
,baposition=nullsourcepos
}
assertion = nullassertion
+-- | Make a partial, exclusive balance assertion.
+balassert :: Amount -> Maybe BalanceAssertion
+balassert amt = Just $ nullassertion{baamount=amt}
+
+-- | Make a total, exclusive balance assertion.
+balassertTot :: Amount -> Maybe BalanceAssertion
+balassertTot amt = Just $ nullassertion{baamount=amt, batotal=True}
+
+-- | Make a partial, inclusive balance assertion.
+balassertParInc :: Amount -> Maybe BalanceAssertion
+balassertParInc amt = Just $ nullassertion{baamount=amt, bainclusive=True}
+
+-- | Make a total, inclusive balance assertion.
+balassertTotInc :: Amount -> Maybe BalanceAssertion
+balassertTotInc amt = Just $ nullassertion{baamount=amt, batotal=True, bainclusive=True}
+
-- Get the original posting, if any.
originalPosting :: Posting -> Posting
-originalPosting p = fromMaybe p $ porigin p
+originalPosting p = fromMaybe p $ poriginal p
-- XXX once rendered user output, but just for debugging now; clean up
showPosting :: Posting -> String
@@ -144,8 +182,8 @@ isBalancedVirtual p = ptype p == BalancedVirtualPosting
hasAmount :: Posting -> Bool
hasAmount = (/= missingmixedamt) . pamount
-isAssignment :: Posting -> Bool
-isAssignment p = not (hasAmount p) && isJust (pbalanceassertion p)
+hasBalanceAssignment :: Posting -> Bool
+hasBalanceAssignment p = not (hasAmount p) && isJust (pbalanceassertion p)
-- | Sorted unique account names referenced by these postings.
accountNamesFromPostings :: [Posting] -> [AccountName]
@@ -176,7 +214,7 @@ postingDate2 p = headDef nulldate $ catMaybes dates
where dates = [pdate2 p
,maybe Nothing tdate2 $ ptransaction p
,pdate p
- ,maybe Nothing (Just . tdate) $ ptransaction p
+ ,fmap tdate (ptransaction p)
]
-- | Get a posting's status. This is cleared or pending if those are
@@ -237,14 +275,14 @@ isEmptyPosting = isZeroMixedAmount . pamount
postingsDateSpan :: [Posting] -> DateSpan
postingsDateSpan [] = DateSpan Nothing Nothing
postingsDateSpan ps = DateSpan (Just $ postingDate $ head ps') (Just $ addDays 1 $ postingDate $ last ps')
- where ps' = sortBy (comparing postingDate) ps
+ where ps' = sortOn postingDate ps
-- --date2-sensitive version, as above.
postingsDateSpan' :: WhichDate -> [Posting] -> DateSpan
postingsDateSpan' _ [] = DateSpan Nothing Nothing
postingsDateSpan' wd ps = DateSpan (Just $ postingdate $ head ps') (Just $ addDays 1 $ postingdate $ last ps')
where
- ps' = sortBy (comparing postingdate) ps
+ ps' = sortOn postingdate ps
postingdate = if wd == PrimaryDate then postingDate else postingDate2
-- AccountName stuff that depends on PostingType
diff --git a/Hledger/Data/RawOptions.hs b/Hledger/Data/RawOptions.hs
index 412c595..fbc47be 100644
--- a/Hledger/Data/RawOptions.hs
+++ b/Hledger/Data/RawOptions.hs
@@ -46,7 +46,7 @@ boolopt :: String -> RawOpts -> Bool
boolopt = inRawOpts
maybestringopt :: String -> RawOpts -> Maybe String
-maybestringopt name = maybe Nothing (Just . T.unpack . stripquotes . T.pack) . lookup name . reverse
+maybestringopt name = fmap (T.unpack . stripquotes . T.pack) . lookup name . reverse
stringopt :: String -> RawOpts -> String
stringopt name = fromMaybe "" . maybestringopt name
diff --git a/Hledger/Data/StringFormat.hs b/Hledger/Data/StringFormat.hs
index 815af00..ede3b0b 100644
--- a/Hledger/Data/StringFormat.hs
+++ b/Hledger/Data/StringFormat.hs
@@ -107,7 +107,7 @@ formatliteralp = do
s <- some c
return $ FormatLiteral s
where
- isPrintableButNotPercentage x = isPrint x && (not $ x == '%')
+ isPrintableButNotPercentage x = isPrint x && x /= '%'
c = (satisfy isPrintableButNotPercentage <?> "printable character")
<|> try (string "%%" >> return '%')
@@ -133,7 +133,7 @@ fieldp = do
<|> try (string "date" >> return DescriptionField)
<|> try (string "description" >> return DescriptionField)
<|> try (string "total" >> return TotalField)
- <|> try (some digitChar >>= (\s -> return $ FieldNo $ read s))
+ <|> try ((FieldNo . read) <$> some digitChar)
----------------------------------------------------------------------
diff --git a/Hledger/Data/Timeclock.hs b/Hledger/Data/Timeclock.hs
index d9f287c..7f22008 100644
--- a/Hledger/Data/Timeclock.hs
+++ b/Hledger/Data/Timeclock.hs
@@ -74,6 +74,7 @@ timeclockEntriesToTransactions now (i:o:rest)
(idate,odate) = (localDay itime,localDay otime)
o' = o{tldatetime=itime{localDay=idate, localTimeOfDay=TimeOfDay 23 59 59}}
i' = i{tldatetime=itime{localDay=addDays 1 idate, localTimeOfDay=midnight}}
+{- HLINT ignore timeclockEntriesToTransactions -}
-- | Convert a timeclock clockin and clockout entry to an equivalent journal
-- transaction, representing the time expenditure. Note this entry is not balanced,
diff --git a/Hledger/Data/Transaction.hs b/Hledger/Data/Transaction.hs
index 7a1fa7e..40725e6 100644
--- a/Hledger/Data/Transaction.hs
+++ b/Hledger/Data/Transaction.hs
@@ -1,4 +1,3 @@
-{-# LANGUAGE FlexibleContexts #-}
{-|
A 'Transaction' represents a movement of some commodity(ies) between two
@@ -8,11 +7,16 @@ tags.
-}
-{-# LANGUAGE OverloadedStrings, LambdaCase #-}
+{-# LANGUAGE FlexibleContexts #-}
+{-# LANGUAGE LambdaCase #-}
+{-# LANGUAGE OverloadedStrings #-}
+{-# LANGUAGE Rank2Types #-}
+{-# LANGUAGE RecordWildCards #-}
module Hledger.Data.Transaction (
-- * Transaction
nulltransaction,
+ transaction,
txnTieKnot,
txnUntieKnot,
-- * operations
@@ -24,13 +28,13 @@ module Hledger.Data.Transaction (
balancedVirtualPostings,
transactionsPostings,
isTransactionBalanced,
+ balanceTransaction,
+ balanceTransactionHelper,
-- nonzerobalanceerror,
-- * date operations
transactionDate2,
-- * arithmetic
transactionPostingBalances,
- balanceTransaction,
- balanceTransactionUpdate,
-- * rendering
showTransaction,
showTransactionUnelided,
@@ -41,13 +45,12 @@ module Hledger.Data.Transaction (
sourceFilePath,
sourceFirstLine,
showGenericSourcePos,
+ annotateErrorWithTransaction,
-- * tests
tests_Transaction
)
where
import Data.List
-import Control.Monad.Except
-import Control.Monad.Identity
import Data.Maybe
import Data.Text (Text)
import qualified Data.Text as T
@@ -93,6 +96,10 @@ nulltransaction = Transaction {
tprecedingcomment=""
}
+-- | Make a simple transaction with the given date and postings.
+transaction :: String -> [Posting] -> Transaction
+transaction datestr ps = txnTieKnot $ nulltransaction{tdate=parsedate datestr, tpostings=ps}
+
{-|
Render a journal transaction as text in the style of Ledger's print command.
@@ -192,9 +199,9 @@ renderCommentLines t = case lines $ T.unpack t of ("":ls) -> "":map commentpref
--
postingsAsLines :: Bool -> Bool -> Transaction -> [Posting] -> [String]
postingsAsLines elide onelineamounts t ps
- | elide && length ps > 1 && all hasAmount ps && isTransactionBalanced Nothing t -- imprecise balanced check
- = (concatMap (postingAsLines False onelineamounts ps) $ init ps) ++ postingAsLines True onelineamounts ps (last ps)
- | otherwise = concatMap (postingAsLines False onelineamounts ps) ps
+ | elide && length ps > 1 && all hasAmount ps && isTransactionBalanced Nothing t -- imprecise balanced check
+ = concatMap (postingAsLines False onelineamounts ps) (init ps) ++ postingAsLines True onelineamounts ps (last ps)
+ | otherwise = concatMap (postingAsLines False onelineamounts ps) ps
-- | Render one posting, on one or more lines, suitable for `print` output.
-- There will be an indented account name, plus one or more of status flag,
@@ -222,7 +229,7 @@ postingAsLines elideamount onelineamounts pstoalignwith p = concat [
| postingblock <- postingblocks]
where
postingblocks = [map rstrip $ lines $ concatTopPadded [statusandaccount, " ", amount, assertion, samelinecomment] | amount <- shownAmounts]
- assertion = maybe "" ((" = " ++) . showAmountWithZeroCommodity . baamount) $ pbalanceassertion p
+ assertion = maybe "" ((' ':).showBalanceAssertion) $ pbalanceassertion p
statusandaccount = indent $ fitString (Just $ minwidth) Nothing False True $ pstatusandacct p
where
-- pad to the maximum account name width, plus 2 to leave room for status flags, to keep amounts aligned
@@ -246,6 +253,10 @@ postingAsLines elideamount onelineamounts pstoalignwith p = concat [
case renderCommentLines (pcomment p) of [] -> ("",[])
c:cs -> (c,cs)
+-- | Render a balance assertion, as the =[=][*] symbol and expected amount.
+showBalanceAssertion BalanceAssertion{..} =
+ "=" ++ ['=' | batotal] ++ ['*' | bainclusive] ++ " " ++ showAmountWithZeroCommodity baamount
+
-- | Render a posting, simply. Used in balance assertion errors.
-- showPostingLine p =
-- indent $
@@ -291,7 +302,7 @@ realPostings :: Transaction -> [Posting]
realPostings = filter isReal . tpostings
assignmentPostings :: Transaction -> [Posting]
-assignmentPostings = filter isAssignment . tpostings
+assignmentPostings = filter hasBalanceAssignment . tpostings
virtualPostings :: Transaction -> [Posting]
virtualPostings = filter isVirtual . tpostings
@@ -300,7 +311,7 @@ balancedVirtualPostings :: Transaction -> [Posting]
balancedVirtualPostings = filter isBalancedVirtual . tpostings
transactionsPostings :: [Transaction] -> [Posting]
-transactionsPostings = concat . map tpostings
+transactionsPostings = concatMap tpostings
-- | Get the sums of a transaction's real, virtual, and balanced virtual postings.
transactionPostingBalances :: Transaction -> (MixedAmount,MixedAmount,MixedAmount)
@@ -324,34 +335,40 @@ isTransactionBalanced styles t =
bvsum' = canonicalise $ costOfMixedAmount bvsum
canonicalise = maybe id canonicaliseMixedAmount styles
--- | Ensure this transaction is balanced, possibly inferring a missing
--- amount or conversion price(s), or return an error message.
--- Balancing is affected by commodity display precisions, so those can
--- (optionally) be provided.
---
--- this fails for example, if there are several missing amounts
--- (possibly with balance assignments)
-balanceTransaction :: Maybe (Map.Map CommoditySymbol AmountStyle)
- -> Transaction -> Either String Transaction
-balanceTransaction stylemap = runIdentity . runExceptT
- . balanceTransactionUpdate (\_ _ -> return ()) stylemap
-
-
--- | More general version of 'balanceTransaction' that takes an update
--- function
-balanceTransactionUpdate :: MonadError String m
- => (AccountName -> MixedAmount -> m ())
- -- ^ update function
- -> Maybe (Map.Map CommoditySymbol AmountStyle)
- -> Transaction -> m Transaction
-balanceTransactionUpdate update mstyles t =
- (finalize =<< inferBalancingAmount update (fromMaybe Map.empty mstyles) t)
- `catchError` (throwError . annotateErrorWithTxn t)
+-- | Balance this transaction, ensuring that its postings
+-- (and its balanced virtual postings) sum to 0,
+-- by inferring a missing amount or conversion price(s) if needed.
+-- Or if balancing is not possible, because the amounts don't sum to 0 or
+-- because there's more than one missing amount, return an error message.
+--
+-- Transactions with balance assignments can have more than one
+-- missing amount; to balance those you should use the more powerful
+-- journalBalanceTransactions.
+--
+-- The "sum to 0" test is done using commodity display precisions,
+-- if provided, so that the result agrees with the numbers users can see.
+--
+balanceTransaction ::
+ Maybe (Map.Map CommoditySymbol AmountStyle) -- ^ commodity display styles
+ -> Transaction
+ -> Either String Transaction
+balanceTransaction mstyles = fmap fst . balanceTransactionHelper mstyles
+
+-- | Helper used by balanceTransaction and balanceTransactionWithBalanceAssignmentAndCheckAssertionsB;
+-- use one of those instead. It also returns a list of accounts
+-- and amounts that were inferred.
+balanceTransactionHelper ::
+ Maybe (Map.Map CommoditySymbol AmountStyle) -- ^ commodity display styles
+ -> Transaction
+ -> Either String (Transaction, [(AccountName, MixedAmount)])
+balanceTransactionHelper mstyles t = do
+ (t', inferredamtsandaccts) <-
+ inferBalancingAmount (fromMaybe Map.empty mstyles) $ inferBalancingPrices t
+ if isTransactionBalanced mstyles t'
+ then Right (txnTieKnot t', inferredamtsandaccts)
+ else Left $ annotateErrorWithTransaction t' $ nonzerobalanceerror t'
+
where
- finalize t' = let t'' = inferBalancingPrices t'
- in if isTransactionBalanced mstyles t''
- then return $ txnTieKnot t''
- else throwError $ nonzerobalanceerror t''
nonzerobalanceerror :: Transaction -> String
nonzerobalanceerror t = printf "could not balance this transaction (%s%s%s)" rmsg sep bvmsg
where
@@ -364,45 +381,52 @@ balanceTransactionUpdate update mstyles t =
++ showMixedAmount (costOfMixedAmount bvsum)
sep = if not (null rmsg) && not (null bvmsg) then "; " else "" :: String
- annotateErrorWithTxn t e = intercalate "\n" [showGenericSourcePos $ tsourcepos t, e, showTransactionUnelided t]
+annotateErrorWithTransaction :: Transaction -> String -> String
+annotateErrorWithTransaction t s = intercalate "\n" [showGenericSourcePos $ tsourcepos t, s, showTransactionUnelided t]
-- | Infer up to one missing amount for this transactions's real postings, and
-- likewise for its balanced virtual postings, if needed; or return an error
--- message if we can't.
+-- message if we can't. Returns the updated transaction and any inferred posting amounts,
+-- with the corresponding accounts, in order).
--
-- We can infer a missing amount when there are multiple postings and exactly
-- one of them is amountless. If the amounts had price(s) the inferred amount
-- have the same price(s), and will be converted to the price commodity.
-inferBalancingAmount :: MonadError String m =>
- (AccountName -> MixedAmount -> m ()) -- ^ update function
- -> Map.Map CommoditySymbol AmountStyle -- ^ standard amount styles
- -> Transaction
- -> m Transaction
-inferBalancingAmount update styles t@Transaction{tpostings=ps}
+inferBalancingAmount ::
+ Map.Map CommoditySymbol AmountStyle -- ^ commodity display styles
+ -> Transaction
+ -> Either String (Transaction, [(AccountName, MixedAmount)])
+inferBalancingAmount styles t@Transaction{tpostings=ps}
| length amountlessrealps > 1
- = throwError "could not balance this transaction - can't have more than one real posting with no amount (remember to put 2 or more spaces before amounts)"
+ = Left $ annotateErrorWithTransaction t "could not balance this transaction - can't have more than one real posting with no amount (remember to put 2 or more spaces before amounts)"
| length amountlessbvps > 1
- = throwError "could not balance this transaction - can't have more than one balanced virtual posting with no amount (remember to put 2 or more spaces before amounts)"
+ = Left $ annotateErrorWithTransaction t "could not balance this transaction - can't have more than one balanced virtual posting with no amount (remember to put 2 or more spaces before amounts)"
| otherwise
- = do postings <- mapM inferamount ps
- return t{tpostings=postings}
+ = let psandinferredamts = map inferamount ps
+ inferredacctsandamts = [(paccount p, amt) | (p, Just amt) <- psandinferredamts]
+ in Right (t{tpostings=map fst psandinferredamts}, inferredacctsandamts)
where
(amountfulrealps, amountlessrealps) = partition hasAmount (realPostings t)
realsum = sumStrict $ map pamount amountfulrealps
(amountfulbvps, amountlessbvps) = partition hasAmount (balancedVirtualPostings t)
bvsum = sumStrict $ map pamount amountfulbvps
- inferamount p@Posting{ptype=RegularPosting}
- | not (hasAmount p) = updateAmount p realsum
- inferamount p@Posting{ptype=BalancedVirtualPosting}
- | not (hasAmount p) = updateAmount p bvsum
- inferamount p = return p
- updateAmount p amt =
- update (paccount p) amt' >> return p { pamount=amt', porigin=Just $ originalPosting p }
- where
- -- Inferred amounts are converted to cost.
- -- Also, ensure the new amount has the standard style for its commodity
- -- (the main amount styling pass happened before this balancing pass).
- amt' = styleMixedAmount styles $ normaliseMixedAmount $ costOfMixedAmount (-amt)
+
+ inferamount :: Posting -> (Posting, Maybe MixedAmount)
+ inferamount p =
+ let
+ minferredamt = case ptype p of
+ RegularPosting | not (hasAmount p) -> Just realsum
+ BalancedVirtualPosting | not (hasAmount p) -> Just bvsum
+ _ -> Nothing
+ in
+ case minferredamt of
+ Nothing -> (p, Nothing)
+ Just a -> (p{pamount=a', poriginal=Just $ originalPosting p}, Just a')
+ where
+ -- Inferred amounts are converted to cost.
+ -- Also ensure the new amount has the standard style for its commodity
+ -- (since the main amount styling pass happened before this balancing pass);
+ a' = styleMixedAmount styles $ normaliseMixedAmount $ costOfMixedAmount (-a)
-- | Infer prices for this transaction's posting amounts, if needed to make
-- the postings balance, and if possible. This is done once for the real
@@ -445,9 +469,7 @@ inferBalancingAmount update styles t@Transaction{tpostings=ps}
inferBalancingPrices :: Transaction -> Transaction
inferBalancingPrices t@Transaction{tpostings=ps} = t{tpostings=ps'}
where
- ps' = map (priceInferrerFor t BalancedVirtualPosting) $
- map (priceInferrerFor t RegularPosting) $
- ps
+ ps' = map (priceInferrerFor t BalancedVirtualPosting . priceInferrerFor t RegularPosting) ps
-- | Generate a posting update function which assigns a suitable balancing
-- price to the posting, if and as appropriate for the given transaction and
@@ -466,7 +488,7 @@ priceInferrerFor t pt = inferprice
inferprice p@Posting{pamount=Mixed [a]}
| caninferprices && ptype p == pt && acommodity a == fromcommodity
- = p{pamount=Mixed [a{aprice=conversionprice}], porigin=Just $ originalPosting p}
+ = p{pamount=Mixed [a{aprice=conversionprice}], poriginal=Just $ originalPosting p}
where
fromcommodity = head $ filter (`elem` sumcommodities) pcommodities -- these heads are ugly but should be safe
conversionprice
@@ -478,7 +500,7 @@ priceInferrerFor t pt = inferprice
tocommodity = head $ filter (/=fromcommodity) sumcommodities
toamount = head $ filter ((==tocommodity).acommodity) sumamounts
unitprice = (aquantity fromamount) `divideAmount` toamount
- unitprecision = max 2 ((asprecision $ astyle $ toamount) + (asprecision $ astyle $ fromamount))
+ unitprecision = max 2 (asprecision (astyle toamount) + asprecision (astyle fromamount))
inferprice p = p
-- Get a transaction's secondary date, defaulting to the primary date.
@@ -502,371 +524,492 @@ postingSetTransaction t p = p{ptransaction=Just t}
-- tests
-tests_Transaction = tests "Transaction" [
-
- tests "showTransactionUnelided" [
- showTransactionUnelided nulltransaction `is` "0000/01/01\n\n"
- ,showTransactionUnelided nulltransaction{
- tdate=parsedate "2012/05/14",
- tdate2=Just $ parsedate "2012/05/15",
- tstatus=Unmarked,
- tcode="code",
- tdescription="desc",
- tcomment="tcomment1\ntcomment2\n",
- ttags=[("ttag1","val1")],
- tpostings=[
- nullposting{
- pstatus=Cleared,
- paccount="a",
- pamount=Mixed [usd 1, hrs 2],
- pcomment="\npcomment2\n",
- ptype=RegularPosting,
- ptags=[("ptag1","val1"),("ptag2","val2")]
- }
- ]
- }
- `is` unlines [
- "2012/05/14=2012/05/15 (code) desc ; tcomment1",
- " ; tcomment2",
- " * a $1.00",
- " ; pcomment2",
- " * a 2.00h",
- " ; pcomment2",
- ""
- ]
- ]
-
- ,tests "postingAsLines" [
- postingAsLines False False [posting] posting `is` [""]
- ,let p = posting{
- pstatus=Cleared,
- paccount="a",
- pamount=Mixed [usd 1, hrs 2],
- pcomment="pcomment1\npcomment2\n tag3: val3 \n",
- ptype=RegularPosting,
- ptags=[("ptag1","val1"),("ptag2","val2")]
- }
- in postingAsLines False False [p] p `is`
- [
- " * a $1.00 ; pcomment1",
- " ; pcomment2",
- " ; tag3: val3 ",
- " * a 2.00h ; pcomment1",
- " ; pcomment2",
- " ; tag3: val3 "
- ]
- ]
-
+tests_Transaction =
+ tests
+ "Transaction"
+ [ tests
+ "showTransactionUnelided"
+ [ showTransactionUnelided nulltransaction `is` "0000/01/01\n\n"
+ , showTransactionUnelided
+ nulltransaction
+ { tdate = parsedate "2012/05/14"
+ , tdate2 = Just $ parsedate "2012/05/15"
+ , tstatus = Unmarked
+ , tcode = "code"
+ , tdescription = "desc"
+ , tcomment = "tcomment1\ntcomment2\n"
+ , ttags = [("ttag1", "val1")]
+ , tpostings =
+ [ nullposting
+ { pstatus = Cleared
+ , paccount = "a"
+ , pamount = Mixed [usd 1, hrs 2]
+ , pcomment = "\npcomment2\n"
+ , ptype = RegularPosting
+ , ptags = [("ptag1", "val1"), ("ptag2", "val2")]
+ }
+ ]
+ } `is`
+ unlines
+ [ "2012/05/14=2012/05/15 (code) desc ; tcomment1"
+ , " ; tcomment2"
+ , " * a $1.00"
+ , " ; pcomment2"
+ , " * a 2.00h"
+ , " ; pcomment2"
+ , ""
+ ]
+ ]
+ , tests
+ "postingAsLines"
+ [ postingAsLines False False [posting] posting `is` [""]
+ , let p =
+ posting
+ { pstatus = Cleared
+ , paccount = "a"
+ , pamount = Mixed [usd 1, hrs 2]
+ , pcomment = "pcomment1\npcomment2\n tag3: val3 \n"
+ , ptype = RegularPosting
+ , ptags = [("ptag1", "val1"), ("ptag2", "val2")]
+ }
+ in postingAsLines False False [p] p `is`
+ [ " * a $1.00 ; pcomment1"
+ , " ; pcomment2"
+ , " ; tag3: val3 "
+ , " * a 2.00h ; pcomment1"
+ , " ; pcomment2"
+ , " ; tag3: val3 "
+ ]
+ ]
-- postingsAsLines
- ,let
-- one implicit amount
- timp = nulltransaction{tpostings=[
- "a" `post` usd 1,
- "b" `post` missingamt
- ]}
+ , let timp = nulltransaction {tpostings = ["a" `post` usd 1, "b" `post` missingamt]}
-- explicit amounts, balanced
- texp = nulltransaction{tpostings=[
- "a" `post` usd 1,
- "b" `post` usd (-1)
- ]}
+ texp = nulltransaction {tpostings = ["a" `post` usd 1, "b" `post` usd (-1)]}
-- explicit amount, only one posting
- texp1 = nulltransaction{tpostings=[
- "(a)" `post` usd 1
- ]}
+ texp1 = nulltransaction {tpostings = ["(a)" `post` usd 1]}
-- explicit amounts, two commodities, explicit balancing price
- texp2 = nulltransaction{tpostings=[
- "a" `post` usd 1,
- "b" `post` (hrs (-1) `at` usd 1)
- ]}
+ texp2 = nulltransaction {tpostings = ["a" `post` usd 1, "b" `post` (hrs (-1) `at` usd 1)]}
-- explicit amounts, two commodities, implicit balancing price
- texp2b = nulltransaction{tpostings=[
- "a" `post` usd 1,
- "b" `post` hrs (-1)
- ]}
+ texp2b = nulltransaction {tpostings = ["a" `post` usd 1, "b" `post` hrs (-1)]}
-- one missing amount, not the last one
- t3 = nulltransaction{tpostings=[
- "a" `post` usd 1
- ,"b" `post` missingamt
- ,"c" `post` usd (-1)
- ]}
+ t3 = nulltransaction {tpostings = ["a" `post` usd 1, "b" `post` missingamt, "c" `post` usd (-1)]}
-- unbalanced amounts when precision is limited (#931)
- t4 = nulltransaction{tpostings=[
- "a" `post` usd (-0.01)
- ,"b" `post` usd (0.005)
- ,"c" `post` usd (0.005)
- ]}
- in
- tests "postingsAsLines" [
-
- test "null-transaction" $
- let t = nulltransaction
- in postingsAsLines True False t (tpostings t) `is` []
-
- ,test "implicit-amount-elide-false" $
- let t = timp in postingsAsLines False False t (tpostings t) `is` [
- " a $1.00"
- ," b" -- implicit amount remains implicit
- ]
-
- ,test "implicit-amount-elide-true" $
- let t = timp in postingsAsLines True False t (tpostings t) `is` [
- " a $1.00"
- ," b" -- implicit amount remains implicit
- ]
-
- ,test "explicit-amounts-elide-false" $
- let t = texp in postingsAsLines False False t (tpostings t) `is` [
- " a $1.00"
- ," b $-1.00" -- both amounts remain explicit
- ]
-
- ,test "explicit-amounts-elide-true" $
- let t = texp in postingsAsLines True False t (tpostings t) `is` [
- " a $1.00"
- ," b" -- explicit amount is made implicit
- ]
-
- ,test "one-explicit-amount-elide-true" $
- let t = texp1 in postingsAsLines True False t (tpostings t) `is` [
- " (a) $1.00" -- explicit amount remains explicit since only one posting
- ]
-
- ,test "explicit-amounts-two-commodities-elide-true" $
- let t = texp2 in postingsAsLines True False t (tpostings t) `is` [
- " a $1.00"
- ," b" -- explicit amount is made implicit since txn is explicitly balanced
- ]
-
- ,test "explicit-amounts-not-explicitly-balanced-elide-true" $
- let t = texp2b in postingsAsLines True False t (tpostings t) `is` [
- " a $1.00"
- ," b -1.00h" -- explicit amount remains explicit since a conversion price would have be inferred to balance
- ]
-
- ,test "implicit-amount-not-last" $
- let t = t3 in postingsAsLines True False t (tpostings t) `is` [
- " a $1.00"
- ," b"
- ," c $-1.00"
- ]
-
- ,_test "ensure-visibly-balanced" $
- let t = t4 in postingsAsLines False False t (tpostings t) `is` [
- " a $-0.01"
- ," b $0.005"
- ," c $0.005"
- ]
-
- ]
-
- ,do
- let inferTransaction :: Transaction -> Either String Transaction
- inferTransaction = runIdentity . runExceptT . inferBalancingAmount (\_ _ -> return ()) Map.empty
- tests "inferBalancingAmount" [
- inferTransaction nulltransaction `is` Right nulltransaction
- ,inferTransaction nulltransaction{
- tpostings=[
- "a" `post` usd (-5),
- "b" `post` missingamt
- ]}
- `is` Right
- nulltransaction{
- tpostings=[
- "a" `post` usd (-5),
- "b" `post` usd 5
- ]}
- ,inferTransaction nulltransaction{
- tpostings=[
- "a" `post` usd (-5),
- "b" `post` (eur 3 @@ usd 4),
- "c" `post` missingamt
- ]}
- `is` Right
- nulltransaction{
- tpostings=[
- "a" `post` usd (-5),
- "b" `post` (eur 3 @@ usd 4),
- "c" `post` usd 1
- ]}
- ]
-
- ,tests "showTransaction" [
- test "show a balanced transaction, eliding last amount" $
- let t = Transaction 0 "" nullsourcepos (parsedate "2007/01/28") Nothing Unmarked "" "coopportunity" "" []
- [posting{paccount="expenses:food:groceries", pamount=Mixed [usd 47.18], ptransaction=Just t}
- ,posting{paccount="assets:checking", pamount=Mixed [usd (-47.18)], ptransaction=Just t}
- ]
- in
- showTransaction t
- `is`
- unlines
- ["2007/01/28 coopportunity"
- ," expenses:food:groceries $47.18"
- ," assets:checking"
- ,""
- ]
-
- ,test "show a balanced transaction, no eliding" $
- (let t = Transaction 0 "" nullsourcepos (parsedate "2007/01/28") Nothing Unmarked "" "coopportunity" "" []
- [posting{paccount="expenses:food:groceries", pamount=Mixed [usd 47.18], ptransaction=Just t}
- ,posting{paccount="assets:checking", pamount=Mixed [usd (-47.18)], ptransaction=Just t}
- ]
- in showTransactionUnelided t)
- `is`
- (unlines
- ["2007/01/28 coopportunity"
- ," expenses:food:groceries $47.18"
- ," assets:checking $-47.18"
- ,""
- ])
-
+ t4 = nulltransaction {tpostings = ["a" `post` usd (-0.01), "b" `post` usd (0.005), "c" `post` usd (0.005)]}
+ in tests
+ "postingsAsLines"
+ [ test "null-transaction" $
+ let t = nulltransaction
+ in postingsAsLines True False t (tpostings t) `is` []
+ , test "implicit-amount-elide-false" $
+ let t = timp
+ in postingsAsLines False False t (tpostings t) `is`
+ [ " a $1.00"
+ , " b" -- implicit amount remains implicit
+ ]
+ , test "implicit-amount-elide-true" $
+ let t = timp
+ in postingsAsLines True False t (tpostings t) `is`
+ [ " a $1.00"
+ , " b" -- implicit amount remains implicit
+ ]
+ , test "explicit-amounts-elide-false" $
+ let t = texp
+ in postingsAsLines False False t (tpostings t) `is`
+ [ " a $1.00"
+ , " b $-1.00" -- both amounts remain explicit
+ ]
+ , test "explicit-amounts-elide-true" $
+ let t = texp
+ in postingsAsLines True False t (tpostings t) `is`
+ [ " a $1.00"
+ , " b" -- explicit amount is made implicit
+ ]
+ , test "one-explicit-amount-elide-true" $
+ let t = texp1
+ in postingsAsLines True False t (tpostings t) `is`
+ [ " (a) $1.00" -- explicit amount remains explicit since only one posting
+ ]
+ , test "explicit-amounts-two-commodities-elide-true" $
+ let t = texp2
+ in postingsAsLines True False t (tpostings t) `is`
+ [ " a $1.00"
+ , " b" -- explicit amount is made implicit since txn is explicitly balanced
+ ]
+ , test "explicit-amounts-not-explicitly-balanced-elide-true" $
+ let t = texp2b
+ in postingsAsLines True False t (tpostings t) `is`
+ [ " a $1.00"
+ , " b -1.00h" -- explicit amount remains explicit since a conversion price would have be inferred to balance
+ ]
+ , test "implicit-amount-not-last" $
+ let t = t3
+ in postingsAsLines True False t (tpostings t) `is`
+ [" a $1.00", " b", " c $-1.00"]
+ , _test "ensure-visibly-balanced" $
+ let t = t4
+ in postingsAsLines False False t (tpostings t) `is`
+ [" a $-0.01", " b $0.005", " c $0.005"]
+ ]
+ , tests
+ "inferBalancingAmount"
+ [ (fst <$> inferBalancingAmount Map.empty nulltransaction) `is` Right nulltransaction
+ , (fst <$> inferBalancingAmount Map.empty nulltransaction{tpostings = ["a" `post` usd (-5), "b" `post` missingamt]}) `is`
+ Right nulltransaction{tpostings = ["a" `post` usd (-5), "b" `post` usd 5]}
+ , (fst <$> inferBalancingAmount Map.empty nulltransaction{tpostings = ["a" `post` usd (-5), "b" `post` (eur 3 @@ usd 4), "c" `post` missingamt]}) `is`
+ Right nulltransaction{tpostings = ["a" `post` usd (-5), "b" `post` (eur 3 @@ usd 4), "c" `post` usd 1]}
+ ]
+ , tests
+ "showTransaction"
+ [ test "show a balanced transaction, eliding last amount" $
+ let t =
+ Transaction
+ 0
+ ""
+ nullsourcepos
+ (parsedate "2007/01/28")
+ Nothing
+ Unmarked
+ ""
+ "coopportunity"
+ ""
+ []
+ [ posting {paccount = "expenses:food:groceries", pamount = Mixed [usd 47.18], ptransaction = Just t}
+ , posting {paccount = "assets:checking", pamount = Mixed [usd (-47.18)], ptransaction = Just t}
+ ]
+ in showTransaction t `is`
+ unlines
+ ["2007/01/28 coopportunity", " expenses:food:groceries $47.18", " assets:checking", ""]
+ , test "show a balanced transaction, no eliding" $
+ (let t =
+ Transaction
+ 0
+ ""
+ nullsourcepos
+ (parsedate "2007/01/28")
+ Nothing
+ Unmarked
+ ""
+ "coopportunity"
+ ""
+ []
+ [ posting {paccount = "expenses:food:groceries", pamount = Mixed [usd 47.18], ptransaction = Just t}
+ , posting {paccount = "assets:checking", pamount = Mixed [usd (-47.18)], ptransaction = Just t}
+ ]
+ in showTransactionUnelided t) `is`
+ (unlines
+ [ "2007/01/28 coopportunity"
+ , " expenses:food:groceries $47.18"
+ , " assets:checking $-47.18"
+ , ""
+ ])
-- document some cases that arise in debug/testing:
- ,test "show an unbalanced transaction, should not elide" $
- (showTransaction
- (txnTieKnot $ Transaction 0 "" nullsourcepos (parsedate "2007/01/28") Nothing Unmarked "" "coopportunity" "" []
- [posting{paccount="expenses:food:groceries", pamount=Mixed [usd 47.18]}
- ,posting{paccount="assets:checking", pamount=Mixed [usd (-47.19)]}
- ]))
- `is`
- (unlines
- ["2007/01/28 coopportunity"
- ," expenses:food:groceries $47.18"
- ," assets:checking $-47.19"
- ,""
- ])
-
- ,test "show an unbalanced transaction with one posting, should not elide" $
- (showTransaction
- (txnTieKnot $ Transaction 0 "" nullsourcepos (parsedate "2007/01/28") Nothing Unmarked "" "coopportunity" "" []
- [posting{paccount="expenses:food:groceries", pamount=Mixed [usd 47.18]}
- ]))
- `is`
- (unlines
- ["2007/01/28 coopportunity"
- ," expenses:food:groceries $47.18"
- ,""
- ])
-
- ,test "show a transaction with one posting and a missing amount" $
- (showTransaction
- (txnTieKnot $ Transaction 0 "" nullsourcepos (parsedate "2007/01/28") Nothing Unmarked "" "coopportunity" "" []
- [posting{paccount="expenses:food:groceries", pamount=missingmixedamt}
- ]))
- `is`
- (unlines
- ["2007/01/28 coopportunity"
- ," expenses:food:groceries"
- ,""
- ])
-
- ,test "show a transaction with a priced commodityless amount" $
- (showTransaction
- (txnTieKnot $ Transaction 0 "" nullsourcepos (parsedate "2010/01/01") Nothing Unmarked "" "x" "" []
- [posting{paccount="a", pamount=Mixed [num 1 `at` (usd 2 `withPrecision` 0)]}
- ,posting{paccount="b", pamount= missingmixedamt}
- ]))
- `is`
- (unlines
- ["2010/01/01 x"
- ," a 1 @ $2"
- ," b"
- ,""
- ])
+ , test "show an unbalanced transaction, should not elide" $
+ (showTransaction
+ (txnTieKnot $
+ Transaction
+ 0
+ ""
+ nullsourcepos
+ (parsedate "2007/01/28")
+ Nothing
+ Unmarked
+ ""
+ "coopportunity"
+ ""
+ []
+ [ posting {paccount = "expenses:food:groceries", pamount = Mixed [usd 47.18]}
+ , posting {paccount = "assets:checking", pamount = Mixed [usd (-47.19)]}
+ ])) `is`
+ (unlines
+ [ "2007/01/28 coopportunity"
+ , " expenses:food:groceries $47.18"
+ , " assets:checking $-47.19"
+ , ""
+ ])
+ , test "show an unbalanced transaction with one posting, should not elide" $
+ (showTransaction
+ (txnTieKnot $
+ Transaction
+ 0
+ ""
+ nullsourcepos
+ (parsedate "2007/01/28")
+ Nothing
+ Unmarked
+ ""
+ "coopportunity"
+ ""
+ []
+ [posting {paccount = "expenses:food:groceries", pamount = Mixed [usd 47.18]}])) `is`
+ (unlines ["2007/01/28 coopportunity", " expenses:food:groceries $47.18", ""])
+ , test "show a transaction with one posting and a missing amount" $
+ (showTransaction
+ (txnTieKnot $
+ Transaction
+ 0
+ ""
+ nullsourcepos
+ (parsedate "2007/01/28")
+ Nothing
+ Unmarked
+ ""
+ "coopportunity"
+ ""
+ []
+ [posting {paccount = "expenses:food:groceries", pamount = missingmixedamt}])) `is`
+ (unlines ["2007/01/28 coopportunity", " expenses:food:groceries", ""])
+ , test "show a transaction with a priced commodityless amount" $
+ (showTransaction
+ (txnTieKnot $
+ Transaction
+ 0
+ ""
+ nullsourcepos
+ (parsedate "2010/01/01")
+ Nothing
+ Unmarked
+ ""
+ "x"
+ ""
+ []
+ [ posting {paccount = "a", pamount = Mixed [num 1 `at` (usd 2 `withPrecision` 0)]}
+ , posting {paccount = "b", pamount = missingmixedamt}
+ ])) `is`
+ (unlines ["2010/01/01 x", " a 1 @ $2", " b", ""])
+ ]
+ , tests
+ "balanceTransaction"
+ [ test "detect unbalanced entry, sign error" $
+ expectLeft
+ (balanceTransaction
+ Nothing
+ (Transaction
+ 0
+ ""
+ nullsourcepos
+ (parsedate "2007/01/28")
+ Nothing
+ Unmarked
+ ""
+ "test"
+ ""
+ []
+ [posting {paccount = "a", pamount = Mixed [usd 1]}, posting {paccount = "b", pamount = Mixed [usd 1]}]))
+ , test "detect unbalanced entry, multiple missing amounts" $
+ expectLeft $
+ balanceTransaction
+ Nothing
+ (Transaction
+ 0
+ ""
+ nullsourcepos
+ (parsedate "2007/01/28")
+ Nothing
+ Unmarked
+ ""
+ "test"
+ ""
+ []
+ [ posting {paccount = "a", pamount = missingmixedamt}
+ , posting {paccount = "b", pamount = missingmixedamt}
+ ])
+ , test "one missing amount is inferred" $
+ (pamount . last . tpostings <$>
+ balanceTransaction
+ Nothing
+ (Transaction
+ 0
+ ""
+ nullsourcepos
+ (parsedate "2007/01/28")
+ Nothing
+ Unmarked
+ ""
+ ""
+ ""
+ []
+ [posting {paccount = "a", pamount = Mixed [usd 1]}, posting {paccount = "b", pamount = missingmixedamt}])) `is`
+ Right (Mixed [usd (-1)])
+ , test "conversion price is inferred" $
+ (pamount . head . tpostings <$>
+ balanceTransaction
+ Nothing
+ (Transaction
+ 0
+ ""
+ nullsourcepos
+ (parsedate "2007/01/28")
+ Nothing
+ Unmarked
+ ""
+ ""
+ ""
+ []
+ [ posting {paccount = "a", pamount = Mixed [usd 1.35]}
+ , posting {paccount = "b", pamount = Mixed [eur (-1)]}
+ ])) `is`
+ Right (Mixed [usd 1.35 @@ (eur 1 `withPrecision` maxprecision)])
+ , test "balanceTransaction balances based on cost if there are unit prices" $
+ expectRight $
+ balanceTransaction
+ Nothing
+ (Transaction
+ 0
+ ""
+ nullsourcepos
+ (parsedate "2011/01/01")
+ Nothing
+ Unmarked
+ ""
+ ""
+ ""
+ []
+ [ posting {paccount = "a", pamount = Mixed [usd 1 `at` eur 2]}
+ , posting {paccount = "a", pamount = Mixed [usd (-2) `at` eur 1]}
+ ])
+ , test "balanceTransaction balances based on cost if there are total prices" $
+ expectRight $
+ balanceTransaction
+ Nothing
+ (Transaction
+ 0
+ ""
+ nullsourcepos
+ (parsedate "2011/01/01")
+ Nothing
+ Unmarked
+ ""
+ ""
+ ""
+ []
+ [ posting {paccount = "a", pamount = Mixed [usd 1 @@ eur 1]}
+ , posting {paccount = "a", pamount = Mixed [usd (-2) @@ eur 1]}
+ ])
+ ]
+ , tests
+ "isTransactionBalanced"
+ [ test "detect balanced" $
+ expect $
+ isTransactionBalanced Nothing $
+ Transaction
+ 0
+ ""
+ nullsourcepos
+ (parsedate "2009/01/01")
+ Nothing
+ Unmarked
+ ""
+ "a"
+ ""
+ []
+ [ posting {paccount = "b", pamount = Mixed [usd 1.00]}
+ , posting {paccount = "c", pamount = Mixed [usd (-1.00)]}
+ ]
+ , test "detect unbalanced" $
+ expect $
+ not $
+ isTransactionBalanced Nothing $
+ Transaction
+ 0
+ ""
+ nullsourcepos
+ (parsedate "2009/01/01")
+ Nothing
+ Unmarked
+ ""
+ "a"
+ ""
+ []
+ [ posting {paccount = "b", pamount = Mixed [usd 1.00]}
+ , posting {paccount = "c", pamount = Mixed [usd (-1.01)]}
+ ]
+ , test "detect unbalanced, one posting" $
+ expect $
+ not $
+ isTransactionBalanced Nothing $
+ Transaction
+ 0
+ ""
+ nullsourcepos
+ (parsedate "2009/01/01")
+ Nothing
+ Unmarked
+ ""
+ "a"
+ ""
+ []
+ [posting {paccount = "b", pamount = Mixed [usd 1.00]}]
+ , test "one zero posting is considered balanced for now" $
+ expect $
+ isTransactionBalanced Nothing $
+ Transaction
+ 0
+ ""
+ nullsourcepos
+ (parsedate "2009/01/01")
+ Nothing
+ Unmarked
+ ""
+ "a"
+ ""
+ []
+ [posting {paccount = "b", pamount = Mixed [usd 0]}]
+ , test "virtual postings don't need to balance" $
+ expect $
+ isTransactionBalanced Nothing $
+ Transaction
+ 0
+ ""
+ nullsourcepos
+ (parsedate "2009/01/01")
+ Nothing
+ Unmarked
+ ""
+ "a"
+ ""
+ []
+ [ posting {paccount = "b", pamount = Mixed [usd 1.00]}
+ , posting {paccount = "c", pamount = Mixed [usd (-1.00)]}
+ , posting {paccount = "d", pamount = Mixed [usd 100], ptype = VirtualPosting}
+ ]
+ , test "balanced virtual postings need to balance among themselves" $
+ expect $
+ not $
+ isTransactionBalanced Nothing $
+ Transaction
+ 0
+ ""
+ nullsourcepos
+ (parsedate "2009/01/01")
+ Nothing
+ Unmarked
+ ""
+ "a"
+ ""
+ []
+ [ posting {paccount = "b", pamount = Mixed [usd 1.00]}
+ , posting {paccount = "c", pamount = Mixed [usd (-1.00)]}
+ , posting {paccount = "d", pamount = Mixed [usd 100], ptype = BalancedVirtualPosting}
+ ]
+ , test "balanced virtual postings need to balance among themselves (2)" $
+ expect $
+ isTransactionBalanced Nothing $
+ Transaction
+ 0
+ ""
+ nullsourcepos
+ (parsedate "2009/01/01")
+ Nothing
+ Unmarked
+ ""
+ "a"
+ ""
+ []
+ [ posting {paccount = "b", pamount = Mixed [usd 1.00]}
+ , posting {paccount = "c", pamount = Mixed [usd (-1.00)]}
+ , posting {paccount = "d", pamount = Mixed [usd 100], ptype = BalancedVirtualPosting}
+ , posting {paccount = "3", pamount = Mixed [usd (-100)], ptype = BalancedVirtualPosting}
+ ]
+ ]
]
-
- ,tests "balanceTransaction" [
- test "detect unbalanced entry, sign error" $
- (expectLeft $ balanceTransaction Nothing
- (Transaction 0 "" nullsourcepos (parsedate "2007/01/28") Nothing Unmarked "" "test" "" []
- [posting{paccount="a", pamount=Mixed [usd 1]}
- ,posting{paccount="b", pamount=Mixed [usd 1]}
- ]))
-
- ,test "detect unbalanced entry, multiple missing amounts" $
- (expectLeft $ balanceTransaction Nothing
- (Transaction 0 "" nullsourcepos (parsedate "2007/01/28") Nothing Unmarked "" "test" "" []
- [posting{paccount="a", pamount=missingmixedamt}
- ,posting{paccount="b", pamount=missingmixedamt}
- ]))
-
- ,test "one missing amount is inferred" $
- (pamount . last . tpostings <$> balanceTransaction
- Nothing
- (Transaction 0 "" nullsourcepos (parsedate "2007/01/28") Nothing Unmarked "" "" "" []
- [posting{paccount="a", pamount=Mixed [usd 1]}
- ,posting{paccount="b", pamount=missingmixedamt}
- ]))
- `is` Right (Mixed [usd (-1)])
-
- ,test "conversion price is inferred" $
- (pamount . head . tpostings <$> balanceTransaction
- Nothing
- (Transaction 0 "" nullsourcepos (parsedate "2007/01/28") Nothing Unmarked "" "" "" []
- [posting{paccount="a", pamount=Mixed [usd 1.35]}
- ,posting{paccount="b", pamount=Mixed [eur (-1)]}
- ]))
- `is` Right (Mixed [usd 1.35 @@ (eur 1 `withPrecision` maxprecision)])
-
- ,test "balanceTransaction balances based on cost if there are unit prices" $
- expectRight $
- balanceTransaction Nothing (Transaction 0 "" nullsourcepos (parsedate "2011/01/01") Nothing Unmarked "" "" "" []
- [posting{paccount="a", pamount=Mixed [usd 1 `at` eur 2]}
- ,posting{paccount="a", pamount=Mixed [usd (-2) `at` eur 1]}
- ])
-
- ,test "balanceTransaction balances based on cost if there are total prices" $
- expectRight $
- balanceTransaction Nothing (Transaction 0 "" nullsourcepos (parsedate "2011/01/01") Nothing Unmarked "" "" "" []
- [posting{paccount="a", pamount=Mixed [usd 1 @@ eur 1]}
- ,posting{paccount="a", pamount=Mixed [usd (-2) @@ eur 1]}
- ])
- ]
-
- ,tests "isTransactionBalanced" [
- test "detect balanced" $ expect $
- isTransactionBalanced Nothing $ Transaction 0 "" nullsourcepos (parsedate "2009/01/01") Nothing Unmarked "" "a" "" []
- [posting{paccount="b", pamount=Mixed [usd 1.00]}
- ,posting{paccount="c", pamount=Mixed [usd (-1.00)]}
- ]
-
- ,test "detect unbalanced" $ expect $
- not $ isTransactionBalanced Nothing $ Transaction 0 "" nullsourcepos (parsedate "2009/01/01") Nothing Unmarked "" "a" "" []
- [posting{paccount="b", pamount=Mixed [usd 1.00]}
- ,posting{paccount="c", pamount=Mixed [usd (-1.01)]}
- ]
-
- ,test "detect unbalanced, one posting" $ expect $
- not $ isTransactionBalanced Nothing $ Transaction 0 "" nullsourcepos (parsedate "2009/01/01") Nothing Unmarked "" "a" "" []
- [posting{paccount="b", pamount=Mixed [usd 1.00]}
- ]
-
- ,test "one zero posting is considered balanced for now" $ expect $
- isTransactionBalanced Nothing $ Transaction 0 "" nullsourcepos (parsedate "2009/01/01") Nothing Unmarked "" "a" "" []
- [posting{paccount="b", pamount=Mixed [usd 0]}
- ]
-
- ,test "virtual postings don't need to balance" $ expect $
- isTransactionBalanced Nothing $ Transaction 0 "" nullsourcepos (parsedate "2009/01/01") Nothing Unmarked "" "a" "" []
- [posting{paccount="b", pamount=Mixed [usd 1.00]}
- ,posting{paccount="c", pamount=Mixed [usd (-1.00)]}
- ,posting{paccount="d", pamount=Mixed [usd 100], ptype=VirtualPosting}
- ]
-
- ,test "balanced virtual postings need to balance among themselves" $ expect $
- not $ isTransactionBalanced Nothing $ Transaction 0 "" nullsourcepos (parsedate "2009/01/01") Nothing Unmarked "" "a" "" []
- [posting{paccount="b", pamount=Mixed [usd 1.00]}
- ,posting{paccount="c", pamount=Mixed [usd (-1.00)]}
- ,posting{paccount="d", pamount=Mixed [usd 100], ptype=BalancedVirtualPosting}
- ]
-
- ,test "balanced virtual postings need to balance among themselves (2)" $ expect $
- isTransactionBalanced Nothing $ Transaction 0 "" nullsourcepos (parsedate "2009/01/01") Nothing Unmarked "" "a" "" []
- [posting{paccount="b", pamount=Mixed [usd 1.00]}
- ,posting{paccount="c", pamount=Mixed [usd (-1.00)]}
- ,posting{paccount="d", pamount=Mixed [usd 100], ptype=BalancedVirtualPosting}
- ,posting{paccount="3", pamount=Mixed [usd (-100)], ptype=BalancedVirtualPosting}
- ]
-
- ]
-
- ]
diff --git a/Hledger/Data/TransactionModifier.hs b/Hledger/Data/TransactionModifier.hs
index f236559..e11c330 100644
--- a/Hledger/Data/TransactionModifier.hs
+++ b/Hledger/Data/TransactionModifier.hs
@@ -34,7 +34,7 @@ import Hledger.Utils.Debug
-- | Apply all the given transaction modifiers, in turn, to each transaction.
modifyTransactions :: [TransactionModifier] -> [Transaction] -> [Transaction]
-modifyTransactions tmods ts = map applymods ts
+modifyTransactions tmods = map applymods
where
applymods = foldr (flip (.) . transactionModifierToFunction) id tmods
diff --git a/Hledger/Data/Types.hs b/Hledger/Data/Types.hs
index 44680d1..d208328 100644
--- a/Hledger/Data/Types.hs
+++ b/Hledger/Data/Types.hs
@@ -26,6 +26,7 @@ import Control.DeepSeq (NFData)
import Data.Data
import Data.Decimal
import Data.Default
+import Data.Functor (($>))
import Data.List (intercalate)
import Text.Blaze (ToMarkup(..))
--XXX https://hackage.haskell.org/package/containers/docs/Data-Map.html
@@ -237,12 +238,48 @@ instance Show Status where -- custom show.. bad idea.. don't do it..
show Pending = "!"
show Cleared = "*"
--- | 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.
+-- | A balance assertion is a declaration about an account's expected balance
+-- at a certain point (posting date and parse order). They provide additional
+-- error checking and readability to a journal file.
+--
+-- The 'BalanceAssertion' type is also used to represent balance assignments,
+-- which instruct hledger what an account's balance should become at a certain
+-- point.
+--
+-- Different kinds of balance assertions are discussed eg on #290.
+-- Variables include:
+--
+-- - which postings are to be summed (real/virtual; unmarked/pending/cleared; this account/this account including subs)
+--
+-- - which commodities within the balance are to be checked
+--
+-- - whether to do a partial or a total check (disallowing other commodities)
+--
+-- I suspect we want:
+--
+-- 1. partial, subaccount-exclusive, Ledger-compatible assertions. Because
+-- they're what we've always had, and removing them would break some
+-- journals unnecessarily. Implemented with = syntax.
+--
+-- 2. total assertions. Because otherwise assertions are a bit leaky.
+-- Implemented with == syntax.
+--
+-- 3. subaccount-inclusive assertions. Because that's something folks need.
+-- Not implemented.
+--
+-- 4. flexible assertions allowing custom criteria (perhaps arbitrary
+-- queries). Because power users have diverse needs and want to try out
+-- different schemes (assert cleared balances, assert balance from real or
+-- virtual postings, etc.). Not implemented.
+--
+-- 5. multicommodity assertions, asserting the balance of multiple commodities
+-- at once. Not implemented, requires #934.
+--
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'
- baposition :: GenericSourcePos
+ baamount :: Amount, -- ^ the expected balance in a particular commodity
+ batotal :: Bool, -- ^ disallow additional non-asserted commodities ?
+ bainclusive :: Bool, -- ^ include subaccounts when calculating the actual balance ?
+ baposition :: GenericSourcePos -- ^ the assertion's file position, for error reporting
} deriving (Eq,Typeable,Data,Generic,Show)
instance NFData BalanceAssertion
@@ -256,10 +293,11 @@ 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
+ poriginal :: Maybe Posting -- ^ When this posting has been transformed in some way
-- (eg its amount or price was inferred, or the account name was
-- changed by a pivot or budget report), this references the original
-- untransformed posting (which will have Nothing in this field).
@@ -268,7 +306,7 @@ data Posting = Posting {
instance NFData Posting
-- The equality test for postings ignores the parent transaction's
--- identity, to avoid recuring ad infinitum.
+-- identity, to avoid recurring ad infinitum.
-- XXX could check that it's Just or Nothing.
instance Eq Posting where
(==) (Posting a1 b1 c1 d1 e1 f1 g1 h1 i1 _ _) (Posting a2 b2 c2 d2 e2 f2 g2 h2 i2 _ _) = a1==a2 && b1==b2 && c1==c2 && d1==d2 && e1==e2 && f1==f2 && g1==g2 && h1==h2 && i1==i2
@@ -276,17 +314,17 @@ instance Eq Posting where
-- | Posting's show instance elides the parent transaction so as not to recurse forever.
instance Show Posting where
show Posting{..} = "PostingPP {" ++ intercalate ", " [
- ("pdate=" ++ show (show pdate))
- ,("pdate2=" ++ show (show pdate2))
- ,("pstatus=" ++ show (show pstatus))
- ,("paccount=" ++ show paccount)
- ,("pamount=" ++ show pamount)
- ,("pcomment=" ++ show pcomment)
- ,("ptype=" ++ show ptype)
- ,("ptags=" ++ show ptags)
- ,("pbalanceassertion=" ++ show pbalanceassertion)
- ,("ptransaction=" ++ show (const "<txn>" <$> ptransaction))
- ,("porigin=" ++ show porigin)
+ "pdate=" ++ show (show pdate)
+ ,"pdate2=" ++ show (show pdate2)
+ ,"pstatus=" ++ show (show pstatus)
+ ,"paccount=" ++ show paccount
+ ,"pamount=" ++ show pamount
+ ,"pcomment=" ++ show pcomment
+ ,"ptype=" ++ show ptype
+ ,"ptags=" ++ show ptags
+ ,"pbalanceassertion=" ++ show pbalanceassertion
+ ,"ptransaction=" ++ show (ptransaction $> "txn")
+ ,"poriginal=" ++ show poriginal
] ++ "}"
-- TODO: needs renaming, or removal if no longer needed. See also TextPosition in Hledger.UI.Editor
diff --git a/Hledger/Read/Common.hs b/Hledger/Read/Common.hs
index c2be1c8..14f9667 100644
--- a/Hledger/Read/Common.hs
+++ b/Hledger/Read/Common.hs
@@ -728,15 +728,17 @@ balanceassertionp :: JournalParser m BalanceAssertion
balanceassertionp = do
sourcepos <- genericSourcePos <$> lift getSourcePos
char '='
- exact <- optional $ try $ char '='
+ istotal <- fmap isJust $ optional $ try $ char '='
+ isinclusive <- fmap isJust $ optional $ try $ char '*'
lift (skipMany spacenonewline)
-- this amount can have a price; balance assertions ignore it,
-- but balance assignments will use it
a <- amountp <?> "amount (for a balance assertion or assignment)"
return BalanceAssertion
- { baamount = a
- , baexact = isJust exact
- , baposition = sourcepos
+ { baamount = a
+ , batotal = istotal
+ , bainclusive = isinclusive
+ , baposition = sourcepos
}
-- Parse a Ledger-style fixed lot price: {=PRICE}
diff --git a/Hledger/Reports/BudgetReport.hs b/Hledger/Reports/BudgetReport.hs
index 1f2e1e8..23605fb 100644
--- a/Hledger/Reports/BudgetReport.hs
+++ b/Hledger/Reports/BudgetReport.hs
@@ -171,7 +171,7 @@ budgetRollUp budgetedaccts showunbudgeted j = j { jtxns = remapTxn <$> jtxns j }
remapTxn = mapPostings (map remapPosting)
where
mapPostings f t = txnTieKnot $ t { tpostings = f $ tpostings t }
- remapPosting p = p { paccount = remapAccount $ paccount p, porigin = Just . fromMaybe p $ porigin p }
+ remapPosting p = p { paccount = remapAccount $ paccount p, poriginal = Just . fromMaybe p $ poriginal p }
where
remapAccount a
| hasbudget = a
diff --git a/Hledger/Reports/PostingsReport.hs b/Hledger/Reports/PostingsReport.hs
index 1a93f09..1e0a85f 100644
--- a/Hledger/Reports/PostingsReport.hs
+++ b/Hledger/Reports/PostingsReport.hs
@@ -116,7 +116,8 @@ matchedPostingsBeforeAndDuring opts q j (DateSpan mstart mend) =
where
beforestartq = dbg1 "beforestartq" $ dateqtype $ DateSpan Nothing mstart
beforeandduringps =
- dbg1 "ps4" $ sortBy (comparing sortdate) $ -- sort postings by date or date2
+ dbg1 "ps5" $ sortBy (comparing sortdate) $ -- sort postings by date or date2
+ dbg1 "ps4" $ (if invert_ opts then map negatePostingAmount else id) $ -- with --invert, invert amounts
dbg1 "ps3" $ map (filterPostingAmount symq) $ -- remove amount parts which the query's cur: terms would exclude
dbg1 "ps2" $ (if related_ opts then concatMap relatedPostings else id) $ -- with -r, replace each with its sibling postings
dbg1 "ps1" $ filter (beforeandduringq `matchesPosting`) $ -- filter postings by the query, with no start date or depth limit
@@ -135,6 +136,9 @@ matchedPostingsBeforeAndDuring opts q j (DateSpan mstart mend) =
where
dateq = dbg1 "dateq" $ filterQuery queryIsDateOrDate2 $ dbg1 "q" q -- XXX confused by multiple date:/date2: ?
+negatePostingAmount :: Posting -> Posting
+negatePostingAmount p = p { pamount = negate $ pamount p }
+
-- | Generate postings report line items from a list of postings or (with
-- non-Nothing dates attached) summary postings.
postingsReportItems :: [(Posting,Maybe Day)] -> (Posting,Maybe Day) -> WhichDate -> Int -> MixedAmount -> (Int -> MixedAmount -> MixedAmount -> MixedAmount) -> Int -> [PostingsReportItem]
diff --git a/Hledger/Utils.hs b/Hledger/Utils.hs
index be78fa3..f2860bf 100644
--- a/Hledger/Utils.hs
+++ b/Hledger/Utils.hs
@@ -220,6 +220,7 @@ sequence' ms = do
x <- m
go (h . (x :)) ms
+-- | Like mapM but uses sequence'.
{-# INLINABLE mapM' #-}
mapM' :: Monad f => (a -> f b) -> [a] -> f [b]
mapM' f = sequence' . map f
diff --git a/hledger-lib.cabal b/hledger-lib.cabal
index 03d5aed..67fd077 100644
--- a/hledger-lib.cabal
+++ b/hledger-lib.cabal
@@ -4,10 +4,10 @@ cabal-version: 1.12
--
-- see: https://github.com/sol/hpack
--
--- hash: 37a0c290958e641dd8779201025f1614b90535b0922970496375bb95d60024bf
+-- hash: e2c444e055dd9ef61f9cbddeeddf69ce3274e6c2eef4b64301b7107144d7d84b
name: hledger-lib
-version: 1.13.1
+version: 1.14
synopsis: Core data types, parsers and functionality for the hledger accounting tools
description: This is a reusable library containing hledger's core functionality.
.
@@ -25,7 +25,7 @@ author: Simon Michael <simon@joyful.com>
maintainer: Simon Michael <simon@joyful.com>
license: GPL-3
license-file: LICENSE
-tested-with: GHC==7.10.3, GHC==8.0.2, GHC==8.2.2, GHC==8.4.3
+tested-with: GHC==7.10.3, GHC==8.0.2, GHC==8.2.2, GHC==8.4.3, GHC==8.6.3
build-type: Simple
extra-source-files:
CHANGES.md
diff --git a/hledger_csv.5 b/hledger_csv.5
index a64bcdf..2a82395 100644
--- a/hledger_csv.5
+++ b/hledger_csv.5
@@ -1,5 +1,5 @@
-.TH "hledger_csv" "5" "February 2019" "hledger 1.13" "hledger User Manuals"
+.TH "hledger_csv" "5" "March 2019" "hledger 1.14" "hledger User Manuals"
diff --git a/hledger_csv.info b/hledger_csv.info
index 4d6233b..453281f 100644
--- a/hledger_csv.info
+++ b/hledger_csv.info
@@ -3,7 +3,7 @@ This is hledger_csv.info, produced by makeinfo version 6.5 from stdin.

File: hledger_csv.info, Node: Top, Next: CSV RULES, Up: (dir)
-hledger_csv(5) hledger 1.13
+hledger_csv(5) hledger 1.14
***************************
hledger can read CSV (comma-separated value) files as if they were
diff --git a/hledger_csv.txt b/hledger_csv.txt
index 5c55c53..091cd77 100644
--- a/hledger_csv.txt
+++ b/hledger_csv.txt
@@ -249,4 +249,4 @@ SEE ALSO
-hledger 1.13 February 2019 hledger_csv(5)
+hledger 1.14 March 2019 hledger_csv(5)
diff --git a/hledger_journal.5 b/hledger_journal.5
index 435c5dd..84b9bc6 100644
--- a/hledger_journal.5
+++ b/hledger_journal.5
@@ -1,6 +1,6 @@
.\"t
-.TH "hledger_journal" "5" "February 2019" "hledger 1.13" "hledger User Manuals"
+.TH "hledger_journal" "5" "March 2019" "hledger 1.14" "hledger User Manuals"
@@ -491,10 +491,10 @@ which is more correct and provides better error checking.
.SS Balance Assertions
.PP
hledger supports Ledger\-style balance assertions in journal files.
-These look like \f[C]=EXPECTEDBALANCE\f[] following a posting\[aq]s
-amount.
-Eg in this example we assert the expected dollar balance in accounts a
-and b after each posting:
+These look like, for example, \f[C]=\ EXPECTEDBALANCE\f[] following a
+posting\[aq]s amount.
+Eg here we assert the expected dollar balance in accounts a and b after
+each posting:
.IP
.nf
\f[C]
@@ -513,7 +513,7 @@ and report an error if any of them fail.
Balance assertions can protect you from, eg, inadvertently disrupting
reconciled balances while cleaning up old entries.
You can disable them temporarily with the
-\f[C]\-\-ignore\-assertions\f[] flag, which can be useful for
+\f[C]\-I/\-\-ignore\-assertions\f[] flag, which can be useful for
troubleshooting or for reading Ledger files.
.SS Assertions and ordering
.PP
@@ -558,11 +558,10 @@ We could call this a "partial" balance assertion.
To assert the balance of more than one commodity in an account, you can
write multiple postings, each asserting one commodity\[aq]s balance.
.PP
-You can make a stronger kind of balance assertion, by writing a double
-equals sign (\f[C]==EXPECTEDBALANCE\f[]).
-This "complete" balance assertion asserts the absence of other
-commodities (or, that their balance is 0, which to hledger is
-equivalent.)
+You can make a stronger "total" balance assertion by writing a double
+equals sign (\f[C]==\ EXPECTEDBALANCE\f[]).
+This asserts that there are no other unasserted commodities in the
+account (or, that their balance is 0).
.IP
.nf
\f[C]
@@ -619,29 +618,19 @@ generate balance assertions with prices), and because balance
\f[I]assignments\f[] do use them (see below).
.SS Assertions and subaccounts
.PP
-Balance assertions do not count the balance from subaccounts; they check
-the posted account\[aq]s exclusive balance.
-For example:
-.IP
-.nf
-\f[C]
-1/1
-\ \ checking:fund\ \ \ 1\ =\ 1\ \ ;\ post\ to\ this\ subaccount,\ its\ balance\ is\ now\ 1
-\ \ checking\ \ \ \ \ \ \ \ 1\ =\ 1\ \ ;\ post\ to\ the\ parent\ account,\ its\ exclusive\ balance\ is\ now\ 1
-\ \ equity
-\f[]
-.fi
-.PP
-The balance report\[aq]s flat mode shows these exclusive balances more
-clearly:
+The balance assertions above (\f[C]=\f[] and \f[C]==\f[]) do not count
+the balance from subaccounts; they check the account\[aq]s exclusive
+balance only.
+You can assert the balance including subaccounts by writing \f[C]=*\f[]
+or \f[C]==*\f[], eg:
.IP
.nf
\f[C]
-$\ hledger\ bal\ checking\ \-\-flat
-\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 1\ \ checking
-\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 1\ \ checking:fund
-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
-\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2
+2019/1/1
+\ \ equity:opening\ balances
+\ \ checking:a\ \ \ \ \ \ \ 5
+\ \ checking:b\ \ \ \ \ \ \ 5
+\ \ checking\ \ \ \ \ \ \ \ \ 1\ \ ==*\ 11
\f[]
.fi
.SS Assertions and virtual postings
@@ -1753,54 +1742,13 @@ after auto postings are added.
This changed in hledger 1.12+; see #893 for background.
.SH EDITOR SUPPORT
.PP
-Add\-on modes exist for various text editors, to make working with
+Helper modes exist for popular text editors, which make working with
journal files easier.
-They add colour, navigation aids and helpful commands.
-For hledger users who edit the journal file directly (the majority),
-using one of these modes is quite recommended.
-.PP
-These were written with Ledger in mind, but also work with hledger
-files:
-.PP
-.TS
-tab(@);
-lw(12.2n) lw(57.8n).
-T{
-Editor
-T}@T{
-T}
-_
-T{
-Emacs
-T}@T{
-http://www.ledger\-cli.org/3.0/doc/ledger\-mode.html
-T}
-T{
-Vim
-T}@T{
-https://github.com/ledger/vim\-ledger
-T}
-T{
-Sublime Text
-T}@T{
-https://github.com/ledger/ledger/wiki/Editing\-Ledger\-files\-with\-Sublime\-Text\-or\-RubyMine
-T}
-T{
-Textmate
-T}@T{
-https://github.com/ledger/ledger/wiki/Using\-TextMate\-2
-T}
-T{
-Text Wrangler \
-T}@T{
-https://github.com/ledger/ledger/wiki/Editing\-Ledger\-files\-with\-TextWrangler
-T}
-T{
-Visual Studio Code
-T}@T{
-https://marketplace.visualstudio.com/items?itemName=mark\-hansen.hledger\-vscode
-T}
-.TE
+They add colour, formatting, tab completion, and helpful commands, and
+are quite recommended if you edit your journal with a text editor.
+They include ledger\-mode or hledger\-mode for Emacs, vim\-ledger for
+Vim, hledger\-vscode for Visual Studio Code, and others.
+See the [[Cookbook]] at hledger.org for the latest information.
.SH "REPORTING BUGS"
diff --git a/hledger_journal.info b/hledger_journal.info
index f3c744a..5e31f14 100644
--- a/hledger_journal.info
+++ b/hledger_journal.info
@@ -4,7 +4,7 @@ stdin.

File: hledger_journal.info, Node: Top, Next: FILE FORMAT, Up: (dir)
-hledger_journal(5) hledger 1.13
+hledger_journal(5) hledger 1.14
*******************************
hledger's usual data source is a plain text file containing journal
@@ -449,9 +449,9 @@ File: hledger_journal.info, Node: Balance Assertions, Next: Balance Assignment
======================
hledger supports Ledger-style balance assertions in journal files.
-These look like '=EXPECTEDBALANCE' following a posting's amount. Eg in
-this example we assert the expected dollar balance in accounts a and b
-after each posting:
+These look like, for example, '= EXPECTEDBALANCE' following a posting's
+amount. Eg here we assert the expected dollar balance in accounts a and
+b after each posting:
2013/1/1
a $1 =$1
@@ -465,8 +465,8 @@ after each posting:
assertions and report an error if any of them fail. Balance assertions
can protect you from, eg, inadvertently disrupting reconciled balances
while cleaning up old entries. You can disable them temporarily with
-the '--ignore-assertions' flag, which can be useful for troubleshooting
-or for reading Ledger files.
+the '-I/--ignore-assertions' flag, which can be useful for
+troubleshooting or for reading Ledger files.
* Menu:
* Assertions and ordering::
@@ -533,10 +533,10 @@ This is how assertions work in Ledger also. We could call this a
To assert the balance of more than one commodity in an account, you
can write multiple postings, each asserting one commodity's balance.
- You can make a stronger kind of balance assertion, by writing a
-double equals sign ('==EXPECTEDBALANCE'). This "complete" balance
-assertion asserts the absence of other commodities (or, that their
-balance is 0, which to hledger is equivalent.)
+ You can make a stronger "total" balance assertion by writing a double
+equals sign ('== EXPECTEDBALANCE'). This asserts that there are no
+other unasserted commodities in the account (or, that their balance is
+0).
2013/1/1
a $1
@@ -591,22 +591,16 @@ File: hledger_journal.info, Node: Assertions and subaccounts, Next: Assertions
1.9.6 Assertions and subaccounts
--------------------------------
-Balance assertions do not count the balance from subaccounts; they check
-the posted account's exclusive balance. For example:
+The balance assertions above ('=' and '==') do not count the balance
+from subaccounts; they check the account's exclusive balance only. You
+can assert the balance including subaccounts by writing '=*' or '==*',
+eg:
-1/1
- checking:fund 1 = 1 ; post to this subaccount, its balance is now 1
- checking 1 = 1 ; post to the parent account, its exclusive balance is now 1
- equity
-
- The balance report's flat mode shows these exclusive balances more
-clearly:
-
-$ hledger bal checking --flat
- 1 checking
- 1 checking:fund
---------------------
- 2
+2019/1/1
+ equity:opening balances
+ checking:a 5
+ checking:b 5
+ checking 1 ==* 11

File: hledger_journal.info, Node: Assertions and virtual postings, Next: Assertions and precision, Prev: Assertions and subaccounts, Up: Balance Assertions
@@ -1581,26 +1575,12 @@ File: hledger_journal.info, Node: EDITOR SUPPORT, Prev: FILE FORMAT, Up: Top
2 EDITOR SUPPORT
****************
-Add-on modes exist for various text editors, to make working with
-journal files easier. They add colour, navigation aids and helpful
-commands. For hledger users who edit the journal file directly (the
-majority), using one of these modes is quite recommended.
-
- These were written with Ledger in mind, but also work with hledger
-files:
-
-Editor
---------------------------------------------------------------------------
-Emacs http://www.ledger-cli.org/3.0/doc/ledger-mode.html
-Vim https://github.com/ledger/vim-ledger
-Sublime https://github.com/ledger/ledger/wiki/Editing-Ledger-files-with-Sublime-Text-or-RubyMine
-Text
-Textmate https://github.com/ledger/ledger/wiki/Using-TextMate-2
-Text https://github.com/ledger/ledger/wiki/Editing-Ledger-files-with-TextWrangler
-Wrangler
-Visual https://marketplace.visualstudio.com/items?itemName=mark-hansen.hledger-vscode
-Studio
-Code
+Helper modes exist for popular text editors, which make working with
+journal files easier. They add colour, formatting, tab completion, and
+helpful commands, and are quite recommended if you edit your journal
+with a text editor. They include ledger-mode or hledger-mode for Emacs,
+vim-ledger for Vim, hledger-vscode for Visual Studio Code, and others.
+See the [[Cookbook]] at hledger.org for the latest information.

Tag Table:
@@ -1633,81 +1613,81 @@ Node: Virtual Postings15026
Ref: #virtual-postings15185
Node: Balance Assertions16405
Ref: #balance-assertions16580
-Node: Assertions and ordering17531
-Ref: #assertions-and-ordering17717
-Node: Assertions and included files18417
-Ref: #assertions-and-included-files18658
-Node: Assertions and multiple -f options18991
-Ref: #assertions-and-multiple--f-options19245
-Node: Assertions and commodities19377
-Ref: #assertions-and-commodities19607
-Node: Assertions and prices20795
-Ref: #assertions-and-prices21007
-Node: Assertions and subaccounts21447
-Ref: #assertions-and-subaccounts21674
-Node: Assertions and virtual postings22195
-Ref: #assertions-and-virtual-postings22435
-Node: Assertions and precision22577
-Ref: #assertions-and-precision22768
-Node: Balance Assignments23035
-Ref: #balance-assignments23216
-Node: Balance assignments and prices24380
-Ref: #balance-assignments-and-prices24552
-Node: Transaction prices24776
-Ref: #transaction-prices24945
-Node: Comments27213
-Ref: #comments27347
-Node: Tags28517
-Ref: #tags28635
-Node: Directives30037
-Ref: #directives30180
-Node: Comment blocks35787
-Ref: #comment-blocks35932
-Node: Including other files36108
-Ref: #including-other-files36288
-Node: Default year36696
-Ref: #default-year36865
-Node: Declaring commodities37288
-Ref: #declaring-commodities37471
-Node: Default commodity38698
-Ref: #default-commodity38874
-Node: Market prices39510
-Ref: #market-prices39675
-Node: Declaring accounts40516
-Ref: #declaring-accounts40692
-Node: Account comments41617
-Ref: #account-comments41780
-Node: Account subdirectives42175
-Ref: #account-subdirectives42370
-Node: Account types42683
-Ref: #account-types42867
-Node: Account display order44511
-Ref: #account-display-order44681
-Node: Rewriting accounts45810
-Ref: #rewriting-accounts45995
-Node: Basic aliases46729
-Ref: #basic-aliases46875
-Node: Regex aliases47579
-Ref: #regex-aliases47750
-Node: Multiple aliases48468
-Ref: #multiple-aliases48643
-Node: end aliases49141
-Ref: #end-aliases49288
-Node: Default parent account49389
-Ref: #default-parent-account49555
-Node: Periodic transactions50439
-Ref: #periodic-transactions50621
-Node: Two spaces after the period expression51746
-Ref: #two-spaces-after-the-period-expression51991
-Node: Forecasting with periodic transactions52476
-Ref: #forecasting-with-periodic-transactions52766
-Node: Budgeting with periodic transactions54453
-Ref: #budgeting-with-periodic-transactions54692
-Node: Transaction modifiers55151
-Ref: #transaction-modifiers55314
-Node: Auto postings and transaction balancing / inferred amounts / balance assertions57298
-Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions57599
-Node: EDITOR SUPPORT57977
-Ref: #editor-support58095
+Node: Assertions and ordering17538
+Ref: #assertions-and-ordering17724
+Node: Assertions and included files18424
+Ref: #assertions-and-included-files18665
+Node: Assertions and multiple -f options18998
+Ref: #assertions-and-multiple--f-options19252
+Node: Assertions and commodities19384
+Ref: #assertions-and-commodities19614
+Node: Assertions and prices20770
+Ref: #assertions-and-prices20982
+Node: Assertions and subaccounts21422
+Ref: #assertions-and-subaccounts21649
+Node: Assertions and virtual postings21973
+Ref: #assertions-and-virtual-postings22213
+Node: Assertions and precision22355
+Ref: #assertions-and-precision22546
+Node: Balance Assignments22813
+Ref: #balance-assignments22994
+Node: Balance assignments and prices24158
+Ref: #balance-assignments-and-prices24330
+Node: Transaction prices24554
+Ref: #transaction-prices24723
+Node: Comments26991
+Ref: #comments27125
+Node: Tags28295
+Ref: #tags28413
+Node: Directives29815
+Ref: #directives29958
+Node: Comment blocks35565
+Ref: #comment-blocks35710
+Node: Including other files35886
+Ref: #including-other-files36066
+Node: Default year36474
+Ref: #default-year36643
+Node: Declaring commodities37066
+Ref: #declaring-commodities37249
+Node: Default commodity38476
+Ref: #default-commodity38652
+Node: Market prices39288
+Ref: #market-prices39453
+Node: Declaring accounts40294
+Ref: #declaring-accounts40470
+Node: Account comments41395
+Ref: #account-comments41558
+Node: Account subdirectives41953
+Ref: #account-subdirectives42148
+Node: Account types42461
+Ref: #account-types42645
+Node: Account display order44289
+Ref: #account-display-order44459
+Node: Rewriting accounts45588
+Ref: #rewriting-accounts45773
+Node: Basic aliases46507
+Ref: #basic-aliases46653
+Node: Regex aliases47357
+Ref: #regex-aliases47528
+Node: Multiple aliases48246
+Ref: #multiple-aliases48421
+Node: end aliases48919
+Ref: #end-aliases49066
+Node: Default parent account49167
+Ref: #default-parent-account49333
+Node: Periodic transactions50217
+Ref: #periodic-transactions50399
+Node: Two spaces after the period expression51524
+Ref: #two-spaces-after-the-period-expression51769
+Node: Forecasting with periodic transactions52254
+Ref: #forecasting-with-periodic-transactions52544
+Node: Budgeting with periodic transactions54231
+Ref: #budgeting-with-periodic-transactions54470
+Node: Transaction modifiers54929
+Ref: #transaction-modifiers55092
+Node: Auto postings and transaction balancing / inferred amounts / balance assertions57076
+Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions57377
+Node: EDITOR SUPPORT57755
+Ref: #editor-support57873

End Tag Table
diff --git a/hledger_journal.txt b/hledger_journal.txt
index 8bb0772..9ded660 100644
--- a/hledger_journal.txt
+++ b/hledger_journal.txt
@@ -358,9 +358,9 @@ FILE FORMAT
Balance Assertions
hledger supports Ledger-style balance assertions in journal files.
- These look like =EXPECTEDBALANCE following a posting's amount. Eg in
- this example we assert the expected dollar balance in accounts a and b
- after each posting:
+ These look like, for example, = EXPECTEDBALANCE following a posting's
+ amount. Eg here we assert the expected dollar balance in accounts a
+ and b after each posting:
2013/1/1
a $1 =$1
@@ -374,7 +374,7 @@ FILE FORMAT
and report an error if any of them fail. Balance assertions can pro-
tect you from, eg, inadvertently disrupting reconciled balances while
cleaning up old entries. You can disable them temporarily with the
- --ignore-assertions flag, which can be useful for troubleshooting or
+ -I/--ignore-assertions flag, which can be useful for troubleshooting or
for reading Ledger files.
Assertions and ordering
@@ -412,10 +412,9 @@ FILE FORMAT
To assert the balance of more than one commodity in an account, you can
write multiple postings, each asserting one commodity's balance.
- You can make a stronger kind of balance assertion, by writing a double
- equals sign (==EXPECTEDBALANCE). This "complete" balance assertion
- asserts the absence of other commodities (or, that their balance is 0,
- which to hledger is equivalent.)
+ You can make a stronger "total" balance assertion by writing a double
+ equals sign (== EXPECTEDBALANCE). This asserts that there are no other
+ unasserted commodities in the account (or, that their balance is 0).
2013/1/1
a $1
@@ -433,7 +432,7 @@ FILE FORMAT
a 0 == $1
It's not yet possible to make a complete assertion about a balance that
- has multiple commodities. One workaround is to isolate each commodity
+ has multiple commodities. One workaround is to isolate each commodity
into its own subaccount:
2013/1/1
@@ -447,51 +446,44 @@ FILE FORMAT
a:euro 0 == 1
Assertions and prices
- Balance assertions ignore transaction prices, and should normally be
+ Balance assertions ignore transaction prices, and should normally be
written without one:
2019/1/1
(a) $1 @ 1 = $1
- We do allow prices to be written there, however, and print shows them,
- even though they don't affect whether the assertion passes or fails.
- This is for backward compatibility (hledger's close command used to
- generate balance assertions with prices), and because balance assign-
+ We do allow prices to be written there, however, and print shows them,
+ even though they don't affect whether the assertion passes or fails.
+ This is for backward compatibility (hledger's close command used to
+ generate balance assertions with prices), and because balance assign-
ments do use them (see below).
Assertions and subaccounts
- Balance assertions do not count the balance from subaccounts; they
- check the posted account's exclusive balance. For example:
+ The balance assertions above (= and ==) do not count the balance from
+ subaccounts; they check the account's exclusive balance only. You can
+ assert the balance including subaccounts by writing =* or ==*, eg:
- 1/1
- checking:fund 1 = 1 ; post to this subaccount, its balance is now 1
- checking 1 = 1 ; post to the parent account, its exclusive balance is now 1
- equity
-
- The balance report's flat mode shows these exclusive balances more
- clearly:
-
- $ hledger bal checking --flat
- 1 checking
- 1 checking:fund
- --------------------
- 2
+ 2019/1/1
+ equity:opening balances
+ checking:a 5
+ checking:b 5
+ checking 1 ==* 11
Assertions and virtual postings
Balance assertions are checked against all postings, both real and vir-
tual. They are not affected by the --real/-R flag or real: query.
Assertions and precision
- Balance assertions compare the exactly calculated amounts, which are
- not always what is shown by reports. Eg a commodity directive may
- limit the display precision, but this will not affect balance asser-
+ Balance assertions compare the exactly calculated amounts, which are
+ not always what is shown by reports. Eg a commodity directive may
+ limit the display precision, but this will not affect balance asser-
tions. Balance assertion failure messages show exact amounts.
Balance Assignments
- Ledger-style balance assignments are also supported. These are like
- balance assertions, but with no posting amount on the left side of the
- equals sign; instead it is calculated automatically so as to satisfy
- the assertion. This can be a convenience during data entry, eg when
+ Ledger-style balance assignments are also supported. These are like
+ balance assertions, but with no posting amount on the left side of the
+ equals sign; instead it is calculated automatically so as to satisfy
+ the assertion. This can be a convenience during data entry, eg when
setting opening balances:
; starting a new journal, set asset account balances
@@ -509,14 +501,14 @@ FILE FORMAT
expenses:misc
The calculated amount depends on the account's balance in the commodity
- at that point (which depends on the previously-dated postings of the
- commodity to that account since the last balance assertion or assign-
+ at that point (which depends on the previously-dated postings of the
+ commodity to that account since the last balance assertion or assign-
ment). Note that using balance assignments makes your journal a little
less explicit; to know the exact amount posted, you have to run hledger
or do the calculations yourself, instead of just reading it.
Balance assignments and prices
- A transaction price in a balance assignment will cause the calculated
+ A transaction price in a balance assignment will cause the calculated
amount to have that price attached:
2019/1/1
@@ -528,9 +520,9 @@ FILE FORMAT
Transaction prices
Within a transaction, you can note an amount's price in another commod-
- ity. This can be used to document the cost (in a purchase) or selling
- price (in a sale). For example, transaction prices are useful to
- record purchases of a foreign currency. Note transaction prices are
+ ity. This can be used to document the cost (in a purchase) or selling
+ price (in a sale). For example, transaction prices are useful to
+ record purchases of a foreign currency. Note transaction prices are
fixed at the time of the transaction, and do not change over time. See
also market prices, which represent prevailing exchange rates on a cer-
tain date.
@@ -559,7 +551,7 @@ FILE FORMAT
(Ledger users: Ledger uses a different syntax for fixed prices, {=UNIT-
PRICE}, which hledger currently ignores).
- Use the -B/--cost flag to convert amounts to their transaction price's
+ Use the -B/--cost flag to convert amounts to their transaction price's
commodity, if any. (mnemonic: "B" is from "cost Basis", as in Ledger).
Eg here is how -B affects the balance report for the example above:
@@ -570,8 +562,8 @@ FILE FORMAT
$-135 assets:dollars
$135 assets:euros # <- the euros' cost
- Note -B is sensitive to the order of postings when a transaction price
- is inferred: the inferred price will be in the commodity of the last
+ Note -B is sensitive to the order of postings when a transaction price
+ is inferred: the inferred price will be in the commodity of the last
amount. So if example 3's postings are reversed, while the transaction
is equivalent, -B shows something different:
@@ -585,14 +577,14 @@ FILE FORMAT
Comments
Lines in the journal beginning with a semicolon (;) or hash (#) or star
- (*) are comments, and will be ignored. (Star comments cause org-mode
- nodes to be ignored, allowing emacs users to fold and navigate their
+ (*) are comments, and will be ignored. (Star comments cause org-mode
+ nodes to be ignored, allowing emacs users to fold and navigate their
journals with org-mode or orgstruct-mode.)
- You can attach comments to a transaction by writing them after the
- description and/or indented on the following lines (before the post-
- ings). Similarly, you can attach comments to an individual posting by
- writing them after the amount and/or indented on the following lines.
+ You can attach comments to a transaction by writing them after the
+ description and/or indented on the following lines (before the post-
+ ings). Similarly, you can attach comments to an individual posting by
+ writing them after the amount and/or indented on the following lines.
Transaction and posting comments must begin with a semicolon (;).
Some examples:
@@ -616,24 +608,24 @@ FILE FORMAT
; another comment line for posting 2
; a file comment (because not indented)
- You can also comment larger regions of a file using comment and
+ You can also comment larger regions of a file using comment and
end comment directives.
Tags
- Tags are a way to add extra labels or labelled data to postings and
+ Tags are a way to add extra labels or labelled data to postings and
transactions, which you can then search or pivot on.
- A simple tag is a word (which may contain hyphens) followed by a full
+ A simple tag is a word (which may contain hyphens) followed by a full
colon, written inside a transaction or posting comment line:
2017/1/16 bought groceries ; sometag:
- Tags can have a value, which is the text after the colon, up to the
+ Tags can have a value, which is the text after the colon, up to the
next comma or end of line, with leading/trailing whitespace removed:
expenses:food $10 ; a-posting-tag: the tag value
- Note this means hledger's tag values can not contain commas or new-
+ Note this means hledger's tag values can not contain commas or new-
lines. Ending at commas means you can write multiple short tags on one
line, comma separated:
@@ -647,69 +639,70 @@ FILE FORMAT
o "tag2" is another tag, whose value is "some value ..."
- Tags in a transaction comment affect the transaction and all of its
- postings, while tags in a posting comment affect only that posting.
- For example, the following transaction has three tags (A, TAG2,
+ Tags in a transaction comment affect the transaction and all of its
+ postings, while tags in a posting comment affect only that posting.
+ For example, the following transaction has three tags (A, TAG2,
third-tag) and the posting has four (those plus posting-tag):
1/1 a transaction ; A:, TAG2:
; third-tag: a third transaction tag, <- with a value
(a) $1 ; posting-tag:
- Tags are like Ledger's metadata feature, except hledger's tag values
+ Tags are like Ledger's metadata feature, except hledger's tag values
are simple strings.
Directives
- A directive is a line in the journal beginning with a special keyword,
+ A directive is a line in the journal beginning with a special keyword,
that influences how the journal is processed. hledger's directives are
based on a subset of Ledger's, but there are many differences (and also
some differences between hledger versions).
Directives' behaviour and interactions can get a little bit complex, so
- here is a table summarising the directives and their effects, with
+ here is a table summarising the directives and their effects, with
links to more detailed docs.
-
-
-
- direc- end subdi- purpose can affect (as of
+ direc- end subdi- purpose can affect (as of
tive directive rec- 2018/06)
tives
-------------------------------------------------------------------------------------------------
- account any document account names, all entries in all
- text declare account types & dis- files, before or
+ account any document account names, all entries in all
+ text declare account types & dis- files, before or
play order after
+
+
+
+
alias end aliases rewrite account names following
inline/included
entries until end
- of current file or
+ of current file or
end directive
- apply account end apply account prepend a common parent to following
+ apply account end apply account prepend a common parent to following
account names inline/included
entries until end
- of current file or
+ of current file or
end directive
comment end comment ignore part of journal following
inline/included
entries until end
- of current file or
+ of current file or
end directive
- commodity format declare a commodity and its number notation:
+ commodity format declare a commodity and its number notation:
number notation & display following entries
style in that commodity
- in all files; dis-
+ in all files; dis-
play style: amounts
of that commodity
in reports
- D declare a commodity, number commodity: all com-
+ D declare a commodity, number commodity: all com-
notation & display style for modityless entries
- commodityless amounts in all files; num-
- ber notation: fol-
+ commodityless amounts in all files; num-
+ ber notation: fol-
lowing commodity-
- less entries and
+ less entries and
entries in that
- commodity in all
+ commodity in all
files; display
style: amounts of
that commodity in
@@ -720,7 +713,7 @@ FILE FORMAT
commodity commodity in
reports, when -V is
used
- Y declare a year for yearless following
+ Y declare a year for yearless following
dates inline/included
entries until end
of current file
@@ -730,9 +723,9 @@ FILE FORMAT
subdirec- optional indented directive line immediately following a par-
tive ent directive
- number how to interpret numbers when parsing journal entries (the
- notation identity of the decimal separator character). (Currently
- each commodity can have its own notation, even in the same
+ number how to interpret numbers when parsing journal entries (the
+ notation identity of the decimal separator character). (Currently
+ each commodity can have its own notation, even in the same
file.)
display how to display amounts of a commodity in reports (symbol side
style and spacing, digit groups, decimal separator, decimal places)
@@ -740,37 +733,37 @@ FILE FORMAT
scope are affected by a directive
As you can see, directives vary in which journal entries and files they
- affect, and whether they are focussed on input (parsing) or output
+ affect, and whether they are focussed on input (parsing) or output
(reports). Some directives have multiple effects.
- If you have a journal made up of multiple files, or pass multiple -f
- options on the command line, note that directives which affect input
- typically last only until the end of their defining file. This pro-
+ If you have a journal made up of multiple files, or pass multiple -f
+ options on the command line, note that directives which affect input
+ typically last only until the end of their defining file. This pro-
vides more simplicity and predictability, eg reports are not changed by
- writing file options in a different order. It can be surprising at
+ writing file options in a different order. It can be surprising at
times though.
Comment blocks
- A line containing just comment starts a commented region of the file,
+ A line containing just comment starts a commented region of the file,
and a line containing just end comment (or the end of the current file)
ends it. See also comments.
Including other files
- You can pull in the content of additional files by writing an include
+ You can pull in the content of additional files by writing an include
directive, like this:
include path/to/file.journal
- If the path does not begin with a slash, it is relative to the current
- file. The include file path may contain common glob patterns (e.g.
+ If the path does not begin with a slash, it is relative to the current
+ file. The include file path may contain common glob patterns (e.g.
*).
- The include directive can only be used in journal files. It can
+ The include directive can only be used in journal files. It can
include journal, timeclock or timedot files, but not CSV files.
Default year
- You can set a default year to be used for subsequent dates which don't
- specify a year. This is a line beginning with Y followed by the year.
+ You can set a default year to be used for subsequent dates which don't
+ specify a year. This is a line beginning with Y followed by the year.
Eg:
Y2009 ; set default year to 2009
@@ -790,8 +783,8 @@ FILE FORMAT
assets
Declaring commodities
- The commodity directive declares commodities which may be used in the
- journal (though currently we do not enforce this). It may be written
+ The commodity directive declares commodities which may be used in the
+ journal (though currently we do not enforce this). It may be written
on a single line, like this:
; commodity EXAMPLEAMOUNT
@@ -801,8 +794,8 @@ FILE FORMAT
; separating thousands with comma.
commodity 1,000.0000 AAAA
- or on multiple lines, using the "format" subdirective. In this case
- the commodity symbol appears twice and should be the same in both
+ or on multiple lines, using the "format" subdirective. In this case
+ the commodity symbol appears twice and should be the same in both
places:
; commodity SYMBOL
@@ -814,19 +807,19 @@ FILE FORMAT
commodity INR
format INR 9,99,99,999.00
- Commodity directives have a second purpose: they define the standard
+ Commodity directives have a second purpose: they define the standard
display format for amounts in the commodity. Normally the display for-
- mat is inferred from journal entries, but this can be unpredictable;
- declaring it with a commodity directive overrides this and removes
- ambiguity. Towards this end, amounts in commodity directives must
- always be written with a decimal point (a period or comma, followed by
+ mat is inferred from journal entries, but this can be unpredictable;
+ declaring it with a commodity directive overrides this and removes
+ ambiguity. Towards this end, amounts in commodity directives must
+ always be written with a decimal point (a period or comma, followed by
0 or more decimal digits).
Default commodity
- The D directive sets a default commodity (and display format), to be
+ The D directive sets a default commodity (and display format), to be
used for amounts without a commodity symbol (ie, plain numbers). (Note
- this differs from Ledger's default commodity directive.) The commodity
- and display format will be applied to all subsequent commodity-less
+ this differs from Ledger's default commodity directive.) The commodity
+ and display format will be applied to all subsequent commodity-less
amounts, or until the next D directive.
# commodity-less amounts should be treated as dollars
@@ -841,9 +834,9 @@ FILE FORMAT
a decimal point.
Market prices
- The P directive declares a market price, which is an exchange rate
+ The P directive declares a market price, which is an exchange rate
between two commodities on a certain date. (In Ledger, they are called
- "historical prices".) These are often obtained from a stock exchange,
+ "historical prices".) These are often obtained from a stock exchange,
cryptocurrency exchange, or the foreign exchange market.
Here is the format:
@@ -854,39 +847,39 @@ FILE FORMAT
o COMMODITYA is the symbol of the commodity being priced
- o COMMODITYBAMOUNT is an amount (symbol and quantity) in a second com-
+ o COMMODITYBAMOUNT is an amount (symbol and quantity) in a second com-
modity, giving the price in commodity B of one unit of commodity A.
- These two market price directives say that one euro was worth 1.35 US
+ These two market price directives say that one euro was worth 1.35 US
dollars during 2009, and $1.40 from 2010 onward:
P 2009/1/1 $1.35
P 2010/1/1 $1.40
- The -V/--value flag can be used to convert reported amounts to another
+ The -V/--value flag can be used to convert reported amounts to another
commodity using these prices.
Declaring accounts
- account directives can be used to pre-declare accounts. Though not
+ account directives can be used to pre-declare accounts. Though not
required, they can provide several benefits:
o They can document your intended chart of accounts, providing a refer-
ence.
- o They can store extra information about accounts (account numbers,
+ o They can store extra information about accounts (account numbers,
notes, etc.)
- o They can help hledger know your accounts' types (asset, liability,
- equity, revenue, expense), useful for reports like balancesheet and
+ o They can help hledger know your accounts' types (asset, liability,
+ equity, revenue, expense), useful for reports like balancesheet and
incomestatement.
- o They control account display order in reports, allowing non-alpha-
+ o They control account display order in reports, allowing non-alpha-
betic sorting (eg Revenues to appear above Expenses).
- o They help with account name completion in the add command,
+ o They help with account name completion in the add command,
hledger-iadd, hledger-web, ledger-mode etc.
- The simplest form is just the word account followed by a hledger-style
+ The simplest form is just the word account followed by a hledger-style
account name, eg:
account assets:bank:checking
@@ -904,7 +897,7 @@ FILE FORMAT
the next line instead.
Account subdirectives
- We also allow (and ignore) Ledger-style indented subdirectives, just
+ We also allow (and ignore) Ledger-style indented subdirectives, just
for compatibility.:
account assets:bank:checking
@@ -917,18 +910,18 @@ FILE FORMAT
[LEDGER-STYLE SUBDIRECTIVES, IGNORED]
Account types
- hledger recognises five types (or classes) of account: Asset, Liabil-
- ity, Equity, Revenue, Expense. This is used by a few accounting-aware
+ hledger recognises five types (or classes) of account: Asset, Liabil-
+ ity, Equity, Revenue, Expense. This is used by a few accounting-aware
reports such as balancesheet, incomestatement and cashflow.
Auto-detected account types
If you name your top-level accounts with some variation of assets, lia-
- bilities/debts, equity, revenues/income, or expenses, their types are
+ bilities/debts, equity, revenues/income, or expenses, their types are
detected automatically.
Account types declared with tags
- More generally, you can declare an account's type with an account
- directive, by writing a type: tag in a comment, followed by one of the
+ More generally, you can declare an account's type with an account
+ directive, by writing a type: tag in a comment, followed by one of the
words Asset, Liability, Equity, Revenue, Expense, or one of the letters
ALERX (case insensitive):
@@ -939,8 +932,8 @@ FILE FORMAT
account expenses ; type:Expenses
Account types declared with account type codes
- Or, you can write one of those letters separated from the account name
- by two or more spaces, but this should probably be considered depre-
+ Or, you can write one of those letters separated from the account name
+ by two or more spaces, but this should probably be considered depre-
cated as of hledger 1.13:
account assets A
@@ -950,7 +943,7 @@ FILE FORMAT
account expenses X
Overriding auto-detected types
- If you ever override the types of those auto-detected english account
+ If you ever override the types of those auto-detected english account
names mentioned above, you might need to help the reports a bit. Eg:
; make "liabilities" not have the liability type - who knows why
@@ -961,8 +954,8 @@ FILE FORMAT
account - ; type:L
Account display order
- Account directives also set the order in which accounts are displayed,
- eg in reports, the hledger-ui accounts screen, and the hledger-web
+ Account directives also set the order in which accounts are displayed,
+ eg in reports, the hledger-ui accounts screen, and the hledger-web
sidebar. By default accounts are listed in alphabetical order. But if
you have these account directives in the journal:
@@ -984,16 +977,16 @@ FILE FORMAT
Undeclared accounts, if any, are displayed last, in alphabetical order.
- Note that sorting is done at each level of the account tree (within
- each group of sibling accounts under the same parent). And currently,
+ Note that sorting is done at each level of the account tree (within
+ each group of sibling accounts under the same parent). And currently,
this directive:
account other:zoo
- would influence the position of zoo among other's subaccounts, but not
- the position of other among the top-level accounts. This means: - you
- will sometimes declare parent accounts (eg account other above) that
- you don't intend to post to, just to customize their display order -
+ would influence the position of zoo among other's subaccounts, but not
+ the position of other among the top-level accounts. This means: - you
+ will sometimes declare parent accounts (eg account other above) that
+ you don't intend to post to, just to customize their display order -
sibling accounts stay together (you couldn't display x:y in between a:b
and a:c).
@@ -1012,14 +1005,14 @@ FILE FORMAT
o customising reports
Account aliases also rewrite account names in account directives. They
- do not affect account names being entered via hledger add or
+ do not affect account names being entered via hledger add or
hledger-web.
See also Cookbook: Rewrite account names.
Basic aliases
- To set an account alias, use the alias directive in your journal file.
- This affects all subsequent journal entries in the current file or its
+ To set an account alias, use the alias directive in your journal file.
+ This affects all subsequent journal entries in the current file or its
included files. The spaces around the = are optional:
alias OLD = NEW
@@ -1027,54 +1020,54 @@ FILE FORMAT
Or, you can use the --alias 'OLD=NEW' option on the command line. This
affects all entries. It's useful for trying out aliases interactively.
- OLD and NEW are case sensitive full account names. hledger will
- replace any occurrence of the old account name with the new one. Sub-
+ OLD and NEW are case sensitive full account names. hledger will
+ replace any occurrence of the old account name with the new one. Sub-
accounts are also affected. Eg:
alias checking = assets:bank:wells fargo:checking
# rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a"
Regex aliases
- There is also a more powerful variant that uses a regular expression,
+ There is also a more powerful variant that uses a regular expression,
indicated by the forward slashes:
alias /REGEX/ = REPLACEMENT
or --alias '/REGEX/=REPLACEMENT'.
- REGEX is a case-insensitive regular expression. Anywhere it matches
- inside an account name, the matched part will be replaced by REPLACE-
- MENT. If REGEX contains parenthesised match groups, these can be ref-
+ REGEX is a case-insensitive regular expression. Anywhere it matches
+ inside an account name, the matched part will be replaced by REPLACE-
+ MENT. If REGEX contains parenthesised match groups, these can be ref-
erenced by the usual numeric backreferences in REPLACEMENT. Eg:
alias /^(.+):bank:([^:]+)(.*)/ = \1:\2 \3
# rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking"
- Also note that REPLACEMENT continues to the end of line (or on command
- line, to end of option argument), so it can contain trailing white-
+ Also note that REPLACEMENT continues to the end of line (or on command
+ line, to end of option argument), so it can contain trailing white-
space.
Multiple aliases
- You can define as many aliases as you like using directives or com-
- mand-line options. Aliases are recursive - each alias sees the result
- of applying previous ones. (This is different from Ledger, where
+ You can define as many aliases as you like using directives or com-
+ mand-line options. Aliases are recursive - each alias sees the result
+ of applying previous ones. (This is different from Ledger, where
aliases are non-recursive by default). Aliases are applied in the fol-
lowing order:
- 1. alias directives, most recently seen first (recent directives take
+ 1. alias directives, most recently seen first (recent directives take
precedence over earlier ones; directives not yet seen are ignored)
2. alias options, in the order they appear on the command line
end aliases
- You can clear (forget) all currently defined aliases with the
+ You can clear (forget) all currently defined aliases with the
end aliases directive:
end aliases
Default parent account
- You can specify a parent account which will be prepended to all
- accounts within a section of the journal. Use the apply account and
+ You can specify a parent account which will be prepended to all
+ accounts within a section of the journal. Use the apply account and
end apply account directives like so:
apply account home
@@ -1091,7 +1084,7 @@ FILE FORMAT
home:food $10
home:cash $-10
- If end apply account is omitted, the effect lasts to the end of the
+ If end apply account is omitted, the effect lasts to the end of the
file. Included files are also affected, eg:
apply account business
@@ -1100,18 +1093,18 @@ FILE FORMAT
apply account personal
include personal.journal
- Prior to hledger 1.0, legacy account and end spellings were also sup-
+ Prior to hledger 1.0, legacy account and end spellings were also sup-
ported.
- A default parent account also affects account directives. It does not
- affect account names being entered via hledger add or hledger-web. If
- account aliases are present, they are applied after the default parent
+ A default parent account also affects account directives. It does not
+ affect account names being entered via hledger add or hledger-web. If
+ account aliases are present, they are applied after the default parent
account.
Periodic transactions
- Periodic transaction rules describe transactions that recur. They
+ Periodic transaction rules describe transactions that recur. They
allow you to generate future transactions for forecasting, without hav-
- ing to write them out explicitly in the journal (with --forecast).
+ ing to write them out explicitly in the journal (with --forecast).
Secondly, they also can be used to define budget goals (with --budget).
A periodic transaction rule looks like a normal journal entry, with the
@@ -1122,17 +1115,17 @@ FILE FORMAT
expenses:rent $2000
assets:bank:checking
- There is an additional constraint on the period expression: the start
- date must fall on a natural boundary of the interval. Eg
+ There is an additional constraint on the period expression: the start
+ date must fall on a natural boundary of the interval. Eg
monthly from 2018/1/1 is valid, but monthly from 2018/1/15 is not.
- Partial or relative dates (M/D, D, tomorrow, last week) in the period
- expression can work (useful or not). They will be relative to today's
- date, unless a Y default year directive is in effect, in which case
+ Partial or relative dates (M/D, D, tomorrow, last week) in the period
+ expression can work (useful or not). They will be relative to today's
+ date, unless a Y default year directive is in effect, in which case
they will be relative to Y/1/1.
Two spaces after the period expression
- If the period expression is followed by a transaction description,
+ If the period expression is followed by a transaction description,
these must be separated by two or more spaces. This helps hledger know
where the period expression ends, so that descriptions can not acciden-
tally alter their meaning, as in this example:
@@ -1145,66 +1138,66 @@ FILE FORMAT
income:acme inc
Forecasting with periodic transactions
- With the --forecast flag, each periodic transaction rule generates
+ With the --forecast flag, each periodic transaction rule generates
future transactions recurring at the specified interval. These are not
- saved in the journal, but appear in all reports. They will look like
- normal transactions, but with an extra tag named recur, whose value is
+ saved in the journal, but appear in all reports. They will look like
+ normal transactions, but with an extra tag named recur, whose value is
the generating period expression.
- Forecast transactions start on the first occurrence, and end on the
- last occurrence, of their interval within the forecast period. The
+ Forecast transactions start on the first occurrence, and end on the
+ last occurrence, of their interval within the forecast period. The
forecast period:
o begins on the later of
o the report start date if specified with -b/-p/date:
- o the day after the latest normal (non-periodic) transaction in the
+ o the day after the latest normal (non-periodic) transaction in the
journal, or today if there are no normal transactions.
- o ends on the report end date if specified with -e/-p/date:, or 180
+ o ends on the report end date if specified with -e/-p/date:, or 180
days from today.
- where "today" means the current date at report time. The "later of"
- rule ensures that forecast transactions do not overlap normal transac-
+ where "today" means the current date at report time. The "later of"
+ rule ensures that forecast transactions do not overlap normal transac-
tions in time; they will begin only after normal transactions end.
- Forecasting can be useful for estimating balances into the future, and
- experimenting with different scenarios. Note the start date logic
+ Forecasting can be useful for estimating balances into the future, and
+ experimenting with different scenarios. Note the start date logic
means that forecasted transactions are automatically replaced by normal
transactions as you add those.
Forecasting can also help with data entry: describe most of your trans-
- actions with periodic rules, and every so often copy the output of
+ actions with periodic rules, and every so often copy the output of
print --forecast to the journal.
You can generate one-time transactions too: just write a period expres-
- sion specifying a date with no report interval. (You could also write
- a normal transaction with a future date, but remember this disables
+ sion specifying a date with no report interval. (You could also write
+ a normal transaction with a future date, but remember this disables
forecast transactions on previous dates.)
Budgeting with periodic transactions
- With the --budget flag, currently supported by the balance command,
- each periodic transaction rule declares recurring budget goals for the
- specified accounts. Eg the first example above declares a goal of
- spending $2000 on rent (and also, a goal of depositing $2000 into
- checking) every month. Goals and actual performance can then be com-
+ With the --budget flag, currently supported by the balance command,
+ each periodic transaction rule declares recurring budget goals for the
+ specified accounts. Eg the first example above declares a goal of
+ spending $2000 on rent (and also, a goal of depositing $2000 into
+ checking) every month. Goals and actual performance can then be com-
pared in budget reports.
- For more details, see: balance: Budget report and Cookbook: Budgeting
+ For more details, see: balance: Budget report and Cookbook: Budgeting
and Forecasting.
Transaction modifiers
- Transaction modifier rules describe changes that should be applied
- automatically to certain transactions. They can be enabled by using
- the --auto flag. Currently, just one kind of change is possible:
- adding extra postings. These rule-generated postings are known as
+ Transaction modifier rules describe changes that should be applied
+ automatically to certain transactions. They can be enabled by using
+ the --auto flag. Currently, just one kind of change is possible:
+ adding extra postings. These rule-generated postings are known as
"automated postings" or "auto postings".
- A transaction modifier rule looks quite like a normal transaction,
- except the first line is an equals sign followed by a query that
- matches certain postings (mnemonic: = suggests matching). And each
+ A transaction modifier rule looks quite like a normal transaction,
+ except the first line is an equals sign followed by a query that
+ matches certain postings (mnemonic: = suggests matching). And each
"posting" is actually a posting-generating rule:
= QUERY
@@ -1212,20 +1205,20 @@ FILE FORMAT
ACCT [AMT]
...
- These posting rules look like normal postings, except the amount can
+ These posting rules look like normal postings, except the amount can
be:
- o a normal amount with a commodity symbol, eg $2. This will be used
+ o a normal amount with a commodity symbol, eg $2. This will be used
as-is.
o a number, eg 2. The commodity symbol (if any) from the matched post-
ing will be added to this.
- o a numeric multiplier, eg *2 (a star followed by a number N). The
+ o a numeric multiplier, eg *2 (a star followed by a number N). The
matched posting's amount (and total price, if any) will be multiplied
by N.
- o a multiplier with a commodity symbol, eg *$2 (a star, number N, and
+ o a multiplier with a commodity symbol, eg *$2 (a star, number N, and
symbol S). The matched posting's amount will be multiplied by N, and
its commodity symbol will be replaced with S.
@@ -1265,42 +1258,28 @@ FILE FORMAT
Currently, transaction modifiers are applied / auto postings are added:
- o after missing amounts are inferred, and transactions are checked for
+ o after missing amounts are inferred, and transactions are checked for
balancedness,
o but before balance assertions are checked.
- Note this means that journal entries must be balanced both before and
+ Note this means that journal entries must be balanced both before and
after auto postings are added. This changed in hledger 1.12+; see #893
for background.
EDITOR SUPPORT
- Add-on modes exist for various text editors, to make working with jour-
- nal files easier. They add colour, navigation aids and helpful com-
- mands. For hledger users who edit the journal file directly (the
- majority), using one of these modes is quite recommended.
-
- These were written with Ledger in mind, but also work with hledger
- files:
-
-
- Editor
- --------------------------------------------------------------------------
- Emacs http://www.ledger-cli.org/3.0/doc/ledger-mode.html
- Vim https://github.com/ledger/vim-ledger
- Sublime Text https://github.com/ledger/ledger/wiki/Edit-
- ing-Ledger-files-with-Sublime-Text-or-RubyMine
- Textmate https://github.com/ledger/ledger/wiki/Using-TextMate-2
-
- Text Wran- https://github.com/ledger/ledger/wiki/Edit-
- gler ing-Ledger-files-with-TextWrangler
- Visual Stu- https://marketplace.visualstudio.com/items?item-
- dio Code Name=mark-hansen.hledger-vscode
+ Helper modes exist for popular text editors, which make working with
+ journal files easier. They add colour, formatting, tab completion, and
+ helpful commands, and are quite recommended if you edit your journal
+ with a text editor. They include ledger-mode or hledger-mode for
+ Emacs, vim-ledger for Vim, hledger-vscode for Visual Studio Code, and
+ others. See the [[Cookbook]] at hledger.org for the latest informa-
+ tion.
REPORTING BUGS
- Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
+ Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
or hledger mail list)
@@ -1314,7 +1293,7 @@ COPYRIGHT
SEE ALSO
- hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
+ hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time-
dot(5), ledger(1)
@@ -1322,4 +1301,4 @@ SEE ALSO
-hledger 1.13 February 2019 hledger_journal(5)
+hledger 1.14 March 2019 hledger_journal(5)
diff --git a/hledger_timeclock.5 b/hledger_timeclock.5
index b09b6b4..33c6e52 100644
--- a/hledger_timeclock.5
+++ b/hledger_timeclock.5
@@ -1,5 +1,5 @@
-.TH "hledger_timeclock" "5" "February 2019" "hledger 1.13" "hledger User Manuals"
+.TH "hledger_timeclock" "5" "March 2019" "hledger 1.14" "hledger User Manuals"
diff --git a/hledger_timeclock.info b/hledger_timeclock.info
index 0fa1fa4..1af0e67 100644
--- a/hledger_timeclock.info
+++ b/hledger_timeclock.info
@@ -4,7 +4,7 @@ stdin.

File: hledger_timeclock.info, Node: Top, Up: (dir)
-hledger_timeclock(5) hledger 1.13
+hledger_timeclock(5) hledger 1.14
*********************************
hledger can read timeclock files. As with Ledger, these are (a subset
diff --git a/hledger_timeclock.txt b/hledger_timeclock.txt
index d337cd8..0689e44 100644
--- a/hledger_timeclock.txt
+++ b/hledger_timeclock.txt
@@ -77,4 +77,4 @@ SEE ALSO
-hledger 1.13 February 2019 hledger_timeclock(5)
+hledger 1.14 March 2019 hledger_timeclock(5)
diff --git a/hledger_timedot.5 b/hledger_timedot.5
index 0a0a261..e0ee3cd 100644
--- a/hledger_timedot.5
+++ b/hledger_timedot.5
@@ -1,5 +1,5 @@
-.TH "hledger_timedot" "5" "February 2019" "hledger 1.13" "hledger User Manuals"
+.TH "hledger_timedot" "5" "March 2019" "hledger 1.14" "hledger User Manuals"
diff --git a/hledger_timedot.info b/hledger_timedot.info
index e5f38e0..3eb0e2a 100644
--- a/hledger_timedot.info
+++ b/hledger_timedot.info
@@ -4,7 +4,7 @@ stdin.

File: hledger_timedot.info, Node: Top, Next: FILE FORMAT, Up: (dir)
-hledger_timedot(5) hledger 1.13
+hledger_timedot(5) hledger 1.14
*******************************
Timedot is a plain text format for logging dated, categorised quantities
diff --git a/hledger_timedot.txt b/hledger_timedot.txt
index 35d25eb..99851f3 100644
--- a/hledger_timedot.txt
+++ b/hledger_timedot.txt
@@ -124,4 +124,4 @@ SEE ALSO
-hledger 1.13 February 2019 hledger_timedot(5)
+hledger 1.14 March 2019 hledger_timedot(5)