diff --git a/CHANGES b/CHANGES --- a/CHANGES +++ b/CHANGES @@ -2,7 +2,36 @@ See also the project change log. -# 1.2 (2016/3/31) +# 1.3 (2017/6/30) + +The "uncleared" transaction/posting status, and associated UI flags +and keys, have been renamed to "unmarked" to remove ambiguity and +confusion. This means that we have dropped the `--uncleared` flag, +and our `-U` flag now matches only unmarked things and not pending +ones. See the issue and linked mail list discussion for more +background. (#564) + +Also the -P short flag has been added for --pending, and the -U/-P/-C +and flags can be combined. + +bs/is: fix "Ratio has zero denominator" error (#535) + +bs/is/cf: fix --flat (#552) (Justin Le, Simon Michael) + +bal/bs/is/cf: show negative amounts in red (Simon Michael, Justin Le). +These commands now shows negative amounts in red, when hledger detects +that ANSI codes are supported, (ie when TERM is not "dumb" and stdout +is not being redirected or piped). + +print: show pending mark on postings (fixes #563). +A pending mark on postings is now displayed, just like a cleared mark. +Also there will now be a space between the mark and account name. + +print: amounts are now better aligned, eg when there are posting +status marks or virtual postings + + +# 1.2 (2017/3/31) ## CLI diff --git a/Hledger/Cli.hs b/Hledger/Cli.hs --- a/Hledger/Cli.hs +++ b/Hledger/Cli.hs @@ -75,14 +75,12 @@ -- ,tests_Hledger_Cli_Stats - ,"apply account directive" ~: - let ignoresourcepos j = j{jtxns=map (\t -> t{tsourcepos=nullsourcepos}) (jtxns j)} in - let sameParse str1 str2 = do j1 <- readJournal Nothing Nothing True Nothing str1 >>= either error' (return . ignoresourcepos) - j2 <- readJournal Nothing Nothing True Nothing str2 >>= either error' (return . ignoresourcepos) - j1 `is` j2{jlastreadtime=jlastreadtime j1, jfiles=jfiles j1} --, jparsestate=jparsestate j1} - in TestList - [ - "apply account directive 1" ~: sameParse + ,"apply account directive" ~: + let ignoresourcepos j = j{jtxns=map (\t -> t{tsourcepos=nullsourcepos}) (jtxns j)} in + let sameParse str1 str2 = do j1 <- readJournal Nothing Nothing True Nothing str1 >>= either error' (return . ignoresourcepos) + j2 <- readJournal Nothing Nothing True Nothing str2 >>= either error' (return . ignoresourcepos) + j1 `is` j2{jlastreadtime=jlastreadtime j1, jfiles=jfiles j1} --, jparsestate=jparsestate j1} + in sameParse ("2008/12/07 One\n alpha $-1\n beta $1\n" <> "apply account outer\n2008/12/07 Two\n aigh $-2\n bee $2\n" <> "apply account inner\n2008/12/07 Three\n gamma $-3\n delta $3\n" <> @@ -102,8 +100,6 @@ assertBool "" $ paccount p == "test:from" assertBool "" $ ptype p == VirtualPosting - ] - ,"account aliases" ~: do j <- readJournal Nothing Nothing True Nothing "!alias expenses = equity:draw:personal\n1/1\n (expenses:food) 1\n" >>= either error' return let p = head $ tpostings $ head $ jtxns j @@ -348,7 +344,7 @@ tsourcepos=nullsourcepos, tdate=parsedate "2007/01/01", tdate2=Nothing, - tstatus=Uncleared, + tstatus=Unmarked, tcode="*", tdescription="opening balance", tcomment="", @@ -365,7 +361,7 @@ tsourcepos=nullsourcepos, tdate=parsedate "2007/02/01", tdate2=Nothing, - tstatus=Uncleared, + tstatus=Unmarked, tcode="*", tdescription="ayres suites", tcomment="", @@ -382,7 +378,7 @@ tsourcepos=nullsourcepos, tdate=parsedate "2007/01/02", tdate2=Nothing, - tstatus=Uncleared, + tstatus=Unmarked, tcode="*", tdescription="auto transfer to savings", tcomment="", @@ -399,7 +395,7 @@ tsourcepos=nullsourcepos, tdate=parsedate "2007/01/03", tdate2=Nothing, - tstatus=Uncleared, + tstatus=Unmarked, tcode="*", tdescription="poquito mas", tcomment="", @@ -416,7 +412,7 @@ tsourcepos=nullsourcepos, tdate=parsedate "2007/01/03", tdate2=Nothing, - tstatus=Uncleared, + tstatus=Unmarked, tcode="*", tdescription="verizon", tcomment="", @@ -433,7 +429,7 @@ tsourcepos=nullsourcepos, tdate=parsedate "2007/01/03", tdate2=Nothing, - tstatus=Uncleared, + tstatus=Unmarked, tcode="*", tdescription="discover", tcomment="", diff --git a/Hledger/Cli/Add.hs b/Hledger/Cli/Add.hs --- a/Hledger/Cli/Add.hs +++ b/Hledger/Cli/Add.hs @@ -153,7 +153,7 @@ balancedPostingsWizard = do ps <- postingsWizard es2{esPostings=[]} let t = nulltransaction{tdate=date - ,tstatus=Uncleared + ,tstatus=Unmarked ,tcode=code ,tdescription=desc ,tcomment=comment diff --git a/Hledger/Cli/Balance.hs b/Hledger/Cli/Balance.hs --- a/Hledger/Cli/Balance.hs +++ b/Hledger/Cli/Balance.hs @@ -358,7 +358,7 @@ let -- abuse renderBalanceReportItem to render the total with similar format acctcolwidth = maximum' [T.length fullname | (fullname, _, _, _) <- items] - totallines = map rstrip $ renderBalanceReportItem fmt (T.replicate (acctcolwidth+1) " ", 0, total) + totallines = map rstrip $ renderBalanceReportItem opts fmt (T.replicate (acctcolwidth+1) " ", 0, total) -- with a custom format, extend the line to the full report width; -- otherwise show the usual 20-char line for compatibility overlinewidth | isJust (format_ opts) = maximum' $ map length $ concat lines @@ -399,51 +399,57 @@ -- The output will be one or more lines depending on the format and number of commodities. balanceReportItemAsText :: ReportOpts -> StringFormat -> BalanceReportItem -> [String] balanceReportItemAsText opts fmt (_, accountName, depth, amt) = - renderBalanceReportItem fmt ( + renderBalanceReportItem opts fmt ( maybeAccountNameDrop opts accountName, depth, normaliseMixedAmountSquashPricesForDisplay amt ) -- | Render a balance report item using the given StringFormat, generating one or more lines of text. -renderBalanceReportItem :: StringFormat -> (AccountName, Int, MixedAmount) -> [String] -renderBalanceReportItem fmt (acctname, depth, total) = +renderBalanceReportItem :: ReportOpts -> StringFormat -> (AccountName, Int, MixedAmount) -> [String] +renderBalanceReportItem opts fmt (acctname, depth, total) = lines $ case fmt of OneLine comps -> concatOneLine $ render1 comps TopAligned comps -> concatBottomPadded $ render comps BottomAligned comps -> concatTopPadded $ render comps where - render1 = map (renderComponent1 (acctname, depth, total)) - render = map (renderComponent (acctname, depth, total)) + render1 = map (renderComponent1 opts (acctname, depth, total)) + render = map (renderComponent opts (acctname, depth, total)) defaultTotalFieldWidth = 20 -- | Render one StringFormat component for a balance report item. -renderComponent :: (AccountName, Int, MixedAmount) -> StringFormatComponent -> String -renderComponent _ (FormatLiteral s) = s -renderComponent (acctname, depth, total) (FormatField ljust min max field) = case field of +renderComponent :: ReportOpts -> (AccountName, Int, MixedAmount) -> StringFormatComponent -> String +renderComponent _ _ (FormatLiteral s) = s +renderComponent opts (acctname, depth, total) (FormatField ljust min max field) = case field of DepthSpacerField -> formatString ljust Nothing max $ replicate d ' ' where d = case min of Just m -> depth * m Nothing -> depth AccountField -> formatString ljust min max (T.unpack acctname) - TotalField -> fitStringMulti min max True False $ showMixedAmountWithoutPrice total + TotalField -> fitStringMulti min max True False $ showamt total + where + showamt | color_ opts = cshowMixedAmountWithoutPrice + | otherwise = showMixedAmountWithoutPrice _ -> "" -- | Render one StringFormat component for a balance report item. -- This variant is for use with OneLine string formats; it squashes -- any multi-line rendered values onto one line, comma-and-space separated, -- while still complying with the width spec. -renderComponent1 :: (AccountName, Int, MixedAmount) -> StringFormatComponent -> String -renderComponent1 _ (FormatLiteral s) = s -renderComponent1 (acctname, depth, total) (FormatField ljust min max field) = case field of +renderComponent1 :: ReportOpts -> (AccountName, Int, MixedAmount) -> StringFormatComponent -> String +renderComponent1 _ _ (FormatLiteral s) = s +renderComponent1 opts (acctname, depth, total) (FormatField ljust min max field) = case field of AccountField -> formatString ljust min max ((intercalate ", " . lines) (indented (T.unpack acctname))) where -- better to indent the account name here rather than use a DepthField component -- so that it complies with width spec. Uses a fixed indent step size. indented = ((replicate (depth*2) ' ')++) - TotalField -> fitStringMulti min max True False $ ((intercalate ", " . map strip . lines) (showMixedAmountWithoutPrice total)) + TotalField -> fitStringMulti min max True False $ ((intercalate ", " . map strip . lines) (showamt total)) + where + showamt | color_ opts = cshowMixedAmountWithoutPrice + | otherwise = showMixedAmountWithoutPrice _ -> "" -- multi-column balance reports @@ -489,8 +495,8 @@ -- made using 'balanceReportAsTable'), render it in a format suitable for -- console output. renderBalanceReportTable :: ReportOpts -> Table String String MixedAmount -> String -renderBalanceReportTable (ReportOpts { pretty_tables_ = pretty }) = unlines . trimborder . lines - . render pretty id (" " ++) showMixedAmountOneLineWithoutPrice +renderBalanceReportTable (ReportOpts { pretty_tables_ = pretty, color_=usecolor }) = unlines . trimborder . lines + . render pretty id (" " ++) showamt . align where trimborder = ("":) . (++[""]) . drop 1 . init . map (drop 1 . init) @@ -498,6 +504,8 @@ where acctswidth = maximum' $ map strWidth (headerContents l) l' = padRightWide acctswidth <$> l + showamt | usecolor = cshowMixedAmountOneLineWithoutPrice + | otherwise = showMixedAmountOneLineWithoutPrice -- | Build a 'Table' from a multi-column balance report. balanceReportAsTable :: ReportOpts -> MultiBalanceReport -> Table String String MixedAmount @@ -523,8 +531,8 @@ addtotalrow | no_total_ opts = id | otherwise = (+----+ (row "" $ coltotals - ++ (if row_total_ opts then [tot] else []) - ++ (if average_ opts then [avg] else []) + ++ (if row_total_ opts && not (null coltotals) then [tot] else []) + ++ (if average_ opts && not (null coltotals) then [avg] else []) )) -- | Figure out the overall date span of a multicolumn balance report. diff --git a/Hledger/Cli/BalanceView.hs b/Hledger/Cli/BalanceView.hs --- a/Hledger/Cli/BalanceView.hs +++ b/Hledger/Cli/BalanceView.hs @@ -100,7 +100,7 @@ -> ([Table String String MixedAmount], [[MixedAmount]], Sum MixedAmount) multiBalanceviewQueryReport ropts q0 j t q = ([tabl], [coltotals], Sum tot) where - singlesection = "Cash" `isPrefixOf` t -- TODO temp + singlesection = "Cash" `isPrefixOf` t -- TODO temp ropts' = ropts { no_total_ = singlesection && no_total_ ropts, empty_ = True } q' = And [q0, q j] MultiBalanceReport (dates, rows, (coltotals,tot,avg)) = @@ -129,7 +129,7 @@ unless (no_total_ ropts' || cmd=="cashflow") . mapM_ putStrLn $ -- TODO temp [ "Total:" , "--------------------" - , padleft 20 $ showMixedAmountWithoutPrice (getSum amt) + , padLeftWide 20 $ showamt (getSum amt) ] _ -> do let (tabls, amts, Sum totsum) @@ -137,8 +137,7 @@ sumAmts = case amts of a1:as -> foldl' (zipWith (+)) a1 as [] -> [] - totavg = totsum `divideMixedAmount` - fromIntegral (length sumAmts) + totavg = totsum `divideMixedAmount` fromIntegral (length sumAmts) mergedTabl = case tabls of t1:ts -> foldl' merging t1 ts [] -> T.empty @@ -149,12 +148,14 @@ mergedTabl +====+ row "Total" - (sumAmts ++ (if row_total_ ropts' then [totsum] else []) - ++ (if average_ ropts' then [totavg] else []) + (sumAmts ++ (if row_total_ ropts' && not (null sumAmts) then [totsum] else []) + ++ (if average_ ropts' && not (null sumAmts) then [totavg] else []) ) putStrLn title putStrLn $ renderBalanceReportTable ropts totTabl where + showamt | color_ ropts = cshowMixedAmountWithoutPrice + | otherwise = showMixedAmountWithoutPrice overwriteBalanceType = case reverse $ filter (`elem` ["change","cumulative","historical"]) $ map fst raw of "historical":_ -> Just HistoricalBalance @@ -169,16 +170,19 @@ PeriodChange -> "(Balance Changes)" CumulativeChange -> "(Cumulative Ending Balances)" HistoricalBalance -> "(Historical Ending Balances)" - ropts' = treeIfNotPeriod $ - ropts { balancetype_ = balancetype } - treeIfNotPeriod = case (balancetype, interval_ ropts) of + ropts' = treeIfNotPeriod $ ropts { balancetype_ = balancetype } -- For --historical/--cumulative, we must use multiBalanceReport. -- (This forces --no-elide.) -- These settings format the output in a way that we can convert to -- a normal balance report using singleBalanceReport. See -- Balance.hs for more information. - (HistoricalBalance, NoInterval) -> \o -> o { accountlistmode_ = ALTree } - (CumulativeChange , NoInterval) -> \o -> o { accountlistmode_ = ALTree } - _ -> id + treeIfNotPeriod + | flat_ ropts = id + | otherwise = case (balancetype, interval_ ropts) of + (HistoricalBalance, NoInterval) -> \o -> + o { accountlistmode_ = ALTree } + (CumulativeChange , NoInterval) -> \o -> + o { accountlistmode_ = ALTree } + _ -> id merging (Table hLeft hTop dat) (Table hLeft' _ dat') = Table (T.Group DoubleLine [hLeft, hLeft']) hTop (dat ++ dat') diff --git a/Hledger/Cli/CliOptions.hs b/Hledger/Cli/CliOptions.hs --- a/Hledger/Cli/CliOptions.hs +++ b/Hledger/Cli/CliOptions.hs @@ -139,9 +139,9 @@ ,flagReq ["period","p"] (\s opts -> Right $ setopt "period" s opts) "PERIODEXP" "set start date, end date, and/or report interval all at once (overrides the flags above)" ,flagNone ["date2"] (setboolopt "date2") "show, and make -b/-e/-p/date: match, secondary dates instead" + ,flagNone ["unmarked","U"] (setboolopt "unmarked") "include only unmarked postings/txns (can combine with -P or -C)" + ,flagNone ["pending","P"] (setboolopt "pending") "include only pending postings/txns" ,flagNone ["cleared","C"] (setboolopt "cleared") "include only cleared postings/txns" - ,flagNone ["pending"] (setboolopt "pending") "include only pending postings/txns" - ,flagNone ["uncleared","U"] (setboolopt "uncleared") "include only uncleared (and pending) postings/txns" ,flagNone ["real","R"] (setboolopt "real") "include only non-virtual postings" ,flagReq ["depth"] (\s opts -> Right $ setopt "depth" s opts) "N" "hide accounts/postings deeper than N" ,flagNone ["empty","E"] (setboolopt "empty") "show items with zero amount, normally hidden" diff --git a/Hledger/Cli/Main.hs b/Hledger/Cli/Main.hs --- a/Hledger/Cli/Main.hs +++ b/Hledger/Cli/Main.hs @@ -264,7 +264,7 @@ rewrite add automated postings to certain transactions test run some self tests OTHERCMDS -Help: (see also -h, CMD -h, --help|---man|--info) +Help: (see also -h, CMD -h, --help|--man|--info) help|man|info show any of the hledger manuals in text/man/info format |] diff --git a/Hledger/Cli/Print.hs b/Hledger/Cli/Print.hs --- a/Hledger/Cli/Print.hs +++ b/Hledger/Cli/Print.hs @@ -9,7 +9,7 @@ module Hledger.Cli.Print ( printmode ,print' - ,entriesReportAsText + -- ,entriesReportAsText ,originalTransaction ,tests_Hledger_Cli_Print ) @@ -46,17 +46,6 @@ } where aliases = [] -showTransaction' :: CliOpts -> Transaction -> String -showTransaction' opts - | boolopt "explicit" $ rawopts_ opts = showTransactionUnelided - | otherwise = showTransactionUnelided . originalTransaction - -originalTransaction :: Transaction -> Transaction -originalTransaction t = t { tpostings = map originalPosting' $ tpostings t } where - -- We don't want plain original postings because print wouldn't issue alias - -- directives. Thus we are going to print effective account name. - originalPosting' p = (originalPosting p) { paccount = paccount p } - -- | Print journal transactions in standard format. print' :: CliOpts -> Journal -> IO () print' opts j = do @@ -71,14 +60,21 @@ fmt = outputFormatFromOpts opts (render, ropts') = case fmt of "csv" -> ((++"\n") . printCSV . entriesReportAsCsv, ropts{accountlistmode_=ALFlat}) - _ -> (entriesReportAsText' opts, ropts) + _ -> (entriesReportAsText opts, ropts) writeOutput opts $ render $ entriesReport ropts' q j -entriesReportAsText :: EntriesReport -> String -entriesReportAsText items = concatMap showTransactionUnelided items +entriesReportAsText :: CliOpts -> EntriesReport -> String +entriesReportAsText opts = concatMap (showTransactionUnelided . gettxn) + where + gettxn | boolopt "explicit" $ rawopts_ opts = id -- use the fully inferred/explicit txn + | otherwise = originalTransaction -- use the original txn (more or less) -entriesReportAsText' :: CliOpts -> EntriesReport -> String -entriesReportAsText' = concatMap . showTransaction' +-- Replace this transaction's postings with the original postings if any, but keep the +-- current possibly rewritten account names. +originalTransaction t = t { tpostings = map originalPostingPreservingAccount $ tpostings t } + +-- Get the original posting if any, but keep the current possibly rewritten account name. +originalPostingPreservingAccount p = (originalPosting p) { paccount = paccount p } -- XXX -- tests_showTransactions = [ diff --git a/Hledger/Cli/Stats.hs b/Hledger/Cli/Stats.hs --- a/Hledger/Cli/Stats.hs +++ b/Hledger/Cli/Stats.hs @@ -74,7 +74,7 @@ ,("Accounts", printf "%d (depth %d)" acctnum acctdepth) ,("Commodities", printf "%s (%s)" (show $ length cs) (T.intercalate ", " cs)) -- Transactions this month : %(monthtxns)s (last month in the same period: %(lastmonthtxns)s) - -- Uncleared transactions : %(uncleared)s + -- Unmarked transactions : %(unmarked)s -- Days since reconciliation : %(reconcileelapsed)s -- Days since last transaction : %(recentelapsed)s ] diff --git a/doc/hledger.1 b/doc/hledger.1 --- a/doc/hledger.1 +++ b/doc/hledger.1 @@ -1,6 +1,6 @@ .\"t -.TH "hledger" "1" "March 2017" "hledger 1.2" "hledger User Manuals" +.TH "hledger" "1" "June 2017" "hledger 1.3" "hledger User Manuals" @@ -273,18 +273,18 @@ .RS .RE .TP -.B \f[C]\-C\ \-\-cleared\f[] -include only cleared postings/txns +.B \f[C]\-U\ \-\-unmarked\f[] +include only unmarked postings/txns (can combine with \-P or \-C) .RS .RE .TP -.B \f[C]\-\-pending\f[] +.B \f[C]\-P\ \-\-pending\f[] include only pending postings/txns .RS .RE .TP -.B \f[C]\-U\ \-\-uncleared\f[] -include only uncleared (and pending) postings/txns +.B \f[C]\-C\ \-\-cleared\f[] +include only cleared postings/txns .RS .RE .TP @@ -840,6 +840,71 @@ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \-2\ EUR \f[] .fi +.SS Cost +.PP +The \f[C]\-B/\-\-cost\f[] flag converts amounts to their cost at +transaction time, if they have a transaction price specified. +.SS Market value +.PP +The \f[C]\-V/\-\-value\f[] flag converts the reported amounts to their +market value on the report end date, using the most recent applicable +market prices, when known. +Specifically, when there is a market price (P directive) for the +amount\[aq]s commodity, dated on or before the report end date (see +hledger \-> Report start & end date), the amount will be converted to +the price\[aq]s commodity. +If multiple applicable prices are defined, the latest\-dated one is used +(and if dates are equal, the one last parsed). +.PP +For example: +.IP +.nf +\f[C] +#\ one\ euro\ is\ worth\ this\ many\ dollars\ from\ nov\ 1 +P\ 2016/11/01\ €\ $1.10 + +#\ purchase\ some\ euros\ on\ nov\ 3 +2016/11/3 +\ \ \ \ assets:euros\ \ \ \ \ \ \ \ €100 +\ \ \ \ assets:checking + +#\ the\ euro\ is\ worth\ fewer\ dollars\ by\ dec\ 21 +P\ 2016/12/21\ €\ $1.03 +\f[] +.fi +.PP +How many euros do I have ? +.IP +.nf +\f[C] +$\ hledger\ \-f\ t.j\ bal\ euros +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ €100\ \ assets:euros +\f[] +.fi +.PP +What are they worth on nov 3 ? +(no report end date specified, defaults to the last date in the journal) +.IP +.nf +\f[C] +$\ hledger\ \-f\ t.j\ bal\ euros\ \-V +\ \ \ \ \ \ \ \ \ \ \ \ \ $110.00\ \ assets:euros +\f[] +.fi +.PP +What are they worth on dec 21 ? +.IP +.nf +\f[C] +$\ hledger\ \-f\ t.j\ bal\ euros\ \-V\ \-e\ 2016/12/21 +\ \ \ \ \ \ \ \ \ \ \ \ \ $103.00\ \ assets:euros +\f[] +.fi +.PP +Currently, hledger\[aq]s \-V only uses market prices recorded with P +directives, not transaction prices (unlike Ledger). +.PP +Using \-B and \-V together is allowed. .SS Regular expressions .PP hledger uses regular expressions in a number of places: @@ -903,6 +968,8 @@ .IP \[bu] 2 any of the account terms AND .IP \[bu] 2 +any of the status terms AND +.IP \[bu] 2 all the other terms. .PP The print command: show transactions which @@ -985,8 +1052,8 @@ .RS .RE .TP -.B \f[B]\f[C]status:*,\ status:!,\ status:\f[]\f[] -match cleared, pending, or uncleared/pending transactions respectively +.B \f[B]\f[C]status:,\ status:!,\ status:*\f[]\f[] +match unmarked, pending, or cleared transactions respectively .RS .RE .TP @@ -1289,7 +1356,7 @@ .RE .PP The balance command displays accounts and balances. -It is hledger\[aq]s most featureful and most useful command. +It is hledger\[aq]s most featureful and versatile command. .IP .nf \f[C] @@ -1320,7 +1387,8 @@ "Boring" accounts, which contain a single interesting subaccount and no balance of their own, are elided into the following line for more compact output. -(Use \f[C]\-\-no\-elide\f[] to prevent this.) +(Use \f[C]\-\-no\-elide\f[] to prevent this. +Eliding of boring accounts is not yet supported in multicolumn reports.) .PP Each account\[aq]s balance is the "inclusive" balance \- it includes the balances of any subaccounts. @@ -1494,67 +1562,6 @@ #\ Average\ is\ rounded\ to\ the\ dollar\ here\ since\ all\ journal\ amounts\ are \f[] .fi -.SS Market value -.PP -The \f[C]\-V/\-\-value\f[] flag converts the reported amounts to their -market value on the report end date, using the most recent applicable -market prices, when known. -Specifically, when there is a market price (P directive) for the -amount\[aq]s commodity, dated on or before the report end date (see -hledger \-> Report start & end date), the amount will be converted to -the price\[aq]s commodity. -If multiple applicable prices are defined, the latest\-dated one is used -(and if dates are equal, the one last parsed). -.PP -For example: -.IP -.nf -\f[C] -#\ one\ euro\ is\ worth\ this\ many\ dollars\ from\ nov\ 1 -P\ 2016/11/01\ €\ $1.10 - -#\ purchase\ some\ euros\ on\ nov\ 3 -2016/11/3 -\ \ \ \ assets:euros\ \ \ \ \ \ \ \ €100 -\ \ \ \ assets:checking - -#\ the\ euro\ is\ worth\ fewer\ dollars\ by\ dec\ 21 -P\ 2016/12/21\ €\ $1.03 -\f[] -.fi -.PP -How many euros do I have ? -.IP -.nf -\f[C] -$\ hledger\ \-f\ t.j\ bal\ euros -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ €100\ \ assets:euros -\f[] -.fi -.PP -What are they worth on nov 3 ? -(no report end date specified, defaults to the last date in the journal) -.IP -.nf -\f[C] -$\ hledger\ \-f\ t.j\ bal\ euros\ \-V -\ \ \ \ \ \ \ \ \ \ \ \ \ $110.00\ \ assets:euros -\f[] -.fi -.PP -What are they worth on dec 21 ? -.IP -.nf -\f[C] -$\ hledger\ \-f\ t.j\ bal\ euros\ \-V\ \-e\ 2016/12/21 -\ \ \ \ \ \ \ \ \ \ \ \ \ $103.00\ \ assets:euros -\f[] -.fi -.PP -Currently, hledger\[aq]s \-V only uses market prices recorded with P -directives, not transaction prices (unlike Ledger). -.PP -Using \-B and \-V together is allowed. .SS Custom balance output .PP In simple (non\-multi\-column) balance reports, you can customise the @@ -1627,6 +1634,13 @@ .IP \[bu] 2 \f[C]%20(total)\ \ %2(depth_spacer)%\-(account)\f[] \- the default format for the single\-column balance report +.SS Colour support +.PP +The balance command shows negative amounts in red, if: +.IP \[bu] 2 +the \f[C]TERM\f[] environment variable is not set to \f[C]dumb\f[] +.IP \[bu] 2 +the output is not being redirected or piped anywhere .SS Output destination .PP The balance, print, register and stats commands can write their output diff --git a/doc/hledger.1.info b/doc/hledger.1.info --- a/doc/hledger.1.info +++ b/doc/hledger.1.info @@ -3,7 +3,7 @@  File: hledger.1.info, Node: Top, Next: EXAMPLES, Up: (dir) -hledger(1) hledger 1.2 +hledger(1) hledger 1.3 ********************** This is hledger's command-line interface (there are also curses and web @@ -126,6 +126,8 @@ * Period expressions:: * Depth limiting:: * Pivoting:: +* Cost:: +* Market value:: * Regular expressions::  @@ -212,15 +214,15 @@ '--date2' show, and match with -b/-e/-p/date:, secondary dates instead -'-C --cleared' +'-U --unmarked' - include only cleared postings/txns -'--pending' + include only unmarked postings/txns (can combine with -P or -C) +'-P --pending' include only pending postings/txns -'-U --uncleared' +'-C --cleared' - include only uncleared (and pending) postings/txns + include only cleared postings/txns '-R --real' include only non-virtual postings @@ -508,7 +510,7 @@ N. Use this when you want a summary with less detail.  -File: hledger.1.info, Node: Pivoting, Next: Regular expressions, Prev: Depth limiting, Up: OPTIONS +File: hledger.1.info, Node: Pivoting, Next: Cost, Prev: Depth limiting, Up: OPTIONS 2.11 Pivoting ============= @@ -568,9 +570,67 @@ -2 EUR  -File: hledger.1.info, Node: Regular expressions, Prev: Pivoting, Up: OPTIONS +File: hledger.1.info, Node: Cost, Next: Market value, Prev: Pivoting, Up: OPTIONS -2.12 Regular expressions +2.12 Cost +========= + +The '-B/--cost' flag converts amounts to their cost at transaction time, +if they have a transaction price specified. + + +File: hledger.1.info, Node: Market value, Next: Regular expressions, Prev: Cost, Up: OPTIONS + +2.13 Market value +================= + +The '-V/--value' flag converts the reported amounts to their market +value on the report end date, using the most recent applicable market +prices, when known. Specifically, when there is a market price (P +directive) for the amount's commodity, dated on or before the report end +date (see hledger -> Report start & end date), the amount will be +converted to the price's commodity. If multiple applicable prices are +defined, the latest-dated one is used (and if dates are equal, the one +last parsed). + + For example: + +# one euro is worth this many dollars from nov 1 +P 2016/11/01 € $1.10 + +# purchase some euros on nov 3 +2016/11/3 + assets:euros €100 + assets:checking + +# the euro is worth fewer dollars by dec 21 +P 2016/12/21 € $1.03 + + How many euros do I have ? + +$ hledger -f t.j bal euros + €100 assets:euros + + What are they worth on nov 3 ? (no report end date specified, +defaults to the last date in the journal) + +$ hledger -f t.j bal euros -V + $110.00 assets:euros + + What are they worth on dec 21 ? + +$ hledger -f t.j bal euros -V -e 2016/12/21 + $103.00 assets:euros + + Currently, hledger's -V only uses market prices recorded with P +directives, not transaction prices (unlike Ledger). + + Using -B and -V together is allowed. + + +File: hledger.1.info, Node: Regular expressions, Prev: Market value, Up: OPTIONS + +2.14 Regular expressions ======================== hledger uses regular expressions in a number of places: @@ -626,6 +686,7 @@ * any of the description terms AND * any of the account terms AND + * any of the status terms AND * all the other terms. The print command: show transactions which @@ -683,10 +744,9 @@ *'real:, real:0'* match real or virtual postings respectively -*'status:*, status:!, status:'* +*'status:, status:!, status:*'* - match cleared, pending, or uncleared/pending transactions - respectively + match unmarked, pending, or cleared transactions respectively *'tag:REGEX[=REGEX]'* match by tag name, and optionally also by tag value. Note a tag: @@ -953,7 +1013,7 @@ Use unicode to display prettier tables. The balance command displays accounts and balances. It is hledger's -most featureful and most useful command. +most featureful and versatile command. $ hledger balance $-1 assets @@ -978,7 +1038,8 @@ indented below their parent. "Boring" accounts, which contain a single interesting subaccount and no balance of their own, are elided into the following line for more compact output. (Use '--no-elide' to prevent -this.) +this. Eliding of boring accounts is not yet supported in multicolumn +reports.) Each account's balance is the "inclusive" balance - it includes the balances of any subaccounts. @@ -999,8 +1060,8 @@ * Flat mode:: * Depth limited balance reports:: * Multicolumn balance reports:: -* Market value:: * Custom balance output:: +* Colour support:: * Output destination:: * CSV output:: @@ -1038,7 +1099,7 @@ $1 liabilities  -File: hledger.1.info, Node: Multicolumn balance reports, Next: Market value, Prev: Depth limited balance reports, Up: balance +File: hledger.1.info, Node: Multicolumn balance reports, Next: Custom balance output, Prev: Depth limited balance reports, Up: balance 4.4.3 Multicolumn balance reports --------------------------------- @@ -1138,58 +1199,9 @@ # Average is rounded to the dollar here since all journal amounts are  -File: hledger.1.info, Node: Market value, Next: Custom balance output, Prev: Multicolumn balance reports, Up: balance - -4.4.4 Market value ------------------- - -The '-V/--value' flag converts the reported amounts to their market -value on the report end date, using the most recent applicable market -prices, when known. Specifically, when there is a market price (P -directive) for the amount's commodity, dated on or before the report end -date (see hledger -> Report start & end date), the amount will be -converted to the price's commodity. If multiple applicable prices are -defined, the latest-dated one is used (and if dates are equal, the one -last parsed). - - For example: - -# one euro is worth this many dollars from nov 1 -P 2016/11/01 € $1.10 - -# purchase some euros on nov 3 -2016/11/3 - assets:euros €100 - assets:checking - -# the euro is worth fewer dollars by dec 21 -P 2016/12/21 € $1.03 - - How many euros do I have ? - -$ hledger -f t.j bal euros - €100 assets:euros - - What are they worth on nov 3 ? (no report end date specified, -defaults to the last date in the journal) - -$ hledger -f t.j bal euros -V - $110.00 assets:euros - - What are they worth on dec 21 ? - -$ hledger -f t.j bal euros -V -e 2016/12/21 - $103.00 assets:euros - - Currently, hledger's -V only uses market prices recorded with P -directives, not transaction prices (unlike Ledger). - - Using -B and -V together is allowed. - - -File: hledger.1.info, Node: Custom balance output, Next: Output destination, Prev: Market value, Up: balance +File: hledger.1.info, Node: Custom balance output, Next: Colour support, Prev: Multicolumn balance reports, Up: balance -4.4.5 Custom balance output +4.4.4 Custom balance output --------------------------- In simple (non-multi-column) balance reports, you can customise the @@ -1247,8 +1259,19 @@ the single-column balance report  -File: hledger.1.info, Node: Output destination, Next: CSV output, Prev: Custom balance output, Up: balance +File: hledger.1.info, Node: Colour support, Next: Output destination, Prev: Custom balance output, Up: balance +4.4.5 Colour support +-------------------- + +The balance command shows negative amounts in red, if: + + * the 'TERM' environment variable is not set to 'dumb' + * the output is not being redirected or piped anywhere + + +File: hledger.1.info, Node: Output destination, Next: CSV output, Prev: Colour support, Up: balance + 4.4.6 Output destination ------------------------ @@ -2094,121 +2117,125 @@ Ref: #examples1988 Node: OPTIONS3634 Ref: #options3738 -Node: General options3993 -Ref: #general-options4120 -Node: Command options6643 -Ref: #command-options6796 -Node: Command arguments7194 -Ref: #command-arguments7354 -Node: Special characters7475 -Ref: #special-characters7633 -Node: Input files8801 -Ref: #input-files8939 -Node: Smart dates10902 -Ref: #smart-dates11045 -Node: Report start & end date12024 -Ref: #report-start-end-date12196 -Node: Report intervals13262 -Ref: #report-intervals13427 -Node: Period expressions13828 -Ref: #period-expressions13988 -Node: Depth limiting16328 -Ref: #depth-limiting16474 -Node: Pivoting16675 -Ref: #pivoting16810 -Node: Regular expressions18581 -Ref: #regular-expressions18715 -Node: QUERIES20076 -Ref: #queries20180 -Node: COMMANDS23826 -Ref: #commands23940 -Node: accounts24613 -Ref: #accounts24713 -Node: activity25695 -Ref: #activity25807 -Node: add26166 -Ref: #add26267 -Node: balance28925 -Ref: #balance29038 -Node: Flat mode31980 -Ref: #flat-mode32107 -Node: Depth limited balance reports32527 -Ref: #depth-limited-balance-reports32730 -Node: Multicolumn balance reports33150 -Ref: #multicolumn-balance-reports33352 -Node: Market value38000 -Ref: #market-value38164 -Node: Custom balance output39464 -Ref: #custom-balance-output39637 -Node: Output destination41730 -Ref: #output-destination41895 -Node: CSV output42165 -Ref: #csv-output42284 -Node: balancesheet42681 -Ref: #balancesheet42809 -Node: cashflow44716 -Ref: #cashflow44833 -Node: help46701 -Ref: #help46813 -Node: incomestatement47651 -Ref: #incomestatement47781 -Node: info49673 -Ref: #info49780 -Node: man50144 -Ref: #man50241 -Node: print50646 -Ref: #print50751 -Node: register54507 -Ref: #register54620 -Node: Custom register output59116 -Ref: #custom-register-output59247 -Node: stats60544 -Ref: #stats60650 -Node: test61531 -Ref: #test61618 -Node: ADD-ON COMMANDS61986 -Ref: #add-on-commands62098 -Node: Official add-ons63385 -Ref: #official-add-ons63527 -Node: api63614 -Ref: #api63705 -Node: ui63757 -Ref: #ui63858 -Node: web63916 -Ref: #web64007 -Node: Third party add-ons64053 -Ref: #third-party-add-ons64230 -Node: diff64365 -Ref: #diff64464 -Node: iadd64563 -Ref: #iadd64679 -Node: interest64762 -Ref: #interest64885 -Node: irr64980 -Ref: #irr65080 -Node: Experimental add-ons65158 -Ref: #experimental-add-ons65312 -Node: autosync65705 -Ref: #autosync65819 -Node: budget66058 -Ref: #budget66182 -Node: chart66248 -Ref: #chart66367 -Node: check66438 -Ref: #check66562 -Node: check-dates66629 -Ref: #check-dates66771 -Node: check-dupes66844 -Ref: #check-dupes66987 -Node: equity67064 -Ref: #equity67192 -Node: prices67311 -Ref: #prices67440 -Node: print-unique67495 -Ref: #print-unique67644 -Node: register-match67737 -Ref: #register-match67893 -Node: rewrite67991 -Ref: #rewrite68112 +Node: General options4019 +Ref: #general-options4146 +Node: Command options6684 +Ref: #command-options6837 +Node: Command arguments7235 +Ref: #command-arguments7395 +Node: Special characters7516 +Ref: #special-characters7674 +Node: Input files8842 +Ref: #input-files8980 +Node: Smart dates10943 +Ref: #smart-dates11086 +Node: Report start & end date12065 +Ref: #report-start-end-date12237 +Node: Report intervals13303 +Ref: #report-intervals13468 +Node: Period expressions13869 +Ref: #period-expressions14029 +Node: Depth limiting16369 +Ref: #depth-limiting16515 +Node: Pivoting16716 +Ref: #pivoting16836 +Node: Cost18607 +Ref: #cost18717 +Node: Market value18835 +Ref: #market-value18972 +Node: Regular expressions20272 +Ref: #regular-expressions20410 +Node: QUERIES21771 +Ref: #queries21875 +Node: COMMANDS25540 +Ref: #commands25654 +Node: accounts26327 +Ref: #accounts26427 +Node: activity27409 +Ref: #activity27521 +Node: add27880 +Ref: #add27981 +Node: balance30639 +Ref: #balance30752 +Node: Flat mode33767 +Ref: #flat-mode33894 +Node: Depth limited balance reports34314 +Ref: #depth-limited-balance-reports34517 +Node: Multicolumn balance reports34937 +Ref: #multicolumn-balance-reports35148 +Node: Custom balance output39796 +Ref: #custom-balance-output39980 +Node: Colour support42073 +Ref: #colour-support42234 +Node: Output destination42407 +Ref: #output-destination42565 +Node: CSV output42835 +Ref: #csv-output42954 +Node: balancesheet43351 +Ref: #balancesheet43479 +Node: cashflow45386 +Ref: #cashflow45503 +Node: help47371 +Ref: #help47483 +Node: incomestatement48321 +Ref: #incomestatement48451 +Node: info50343 +Ref: #info50450 +Node: man50814 +Ref: #man50911 +Node: print51316 +Ref: #print51421 +Node: register55177 +Ref: #register55290 +Node: Custom register output59786 +Ref: #custom-register-output59917 +Node: stats61214 +Ref: #stats61320 +Node: test62201 +Ref: #test62288 +Node: ADD-ON COMMANDS62656 +Ref: #add-on-commands62768 +Node: Official add-ons64055 +Ref: #official-add-ons64197 +Node: api64284 +Ref: #api64375 +Node: ui64427 +Ref: #ui64528 +Node: web64586 +Ref: #web64677 +Node: Third party add-ons64723 +Ref: #third-party-add-ons64900 +Node: diff65035 +Ref: #diff65134 +Node: iadd65233 +Ref: #iadd65349 +Node: interest65432 +Ref: #interest65555 +Node: irr65650 +Ref: #irr65750 +Node: Experimental add-ons65828 +Ref: #experimental-add-ons65982 +Node: autosync66375 +Ref: #autosync66489 +Node: budget66728 +Ref: #budget66852 +Node: chart66918 +Ref: #chart67037 +Node: check67108 +Ref: #check67232 +Node: check-dates67299 +Ref: #check-dates67441 +Node: check-dupes67514 +Ref: #check-dupes67657 +Node: equity67734 +Ref: #equity67862 +Node: prices67981 +Ref: #prices68110 +Node: print-unique68165 +Ref: #print-unique68314 +Node: register-match68407 +Ref: #register-match68563 +Node: rewrite68661 +Ref: #rewrite68782  End Tag Table diff --git a/doc/hledger.1.txt b/doc/hledger.1.txt --- a/doc/hledger.1.txt +++ b/doc/hledger.1.txt @@ -182,14 +182,14 @@ --date2 show, and match with -b/-e/-p/date:, secondary dates instead - -C --cleared - include only cleared postings/txns + -U --unmarked + include only unmarked postings/txns (can combine with -P or -C) - --pending + -P --pending include only pending postings/txns - -U --uncleared - include only uncleared (and pending) postings/txns + -C --cleared + include only cleared postings/txns -R --real include only non-virtual postings @@ -518,6 +518,53 @@ -------------------- -2 EUR + Cost + The -B/--cost flag converts amounts to their cost at transaction time, + if they have a transaction price specified. + + Market value + The -V/--value flag converts the reported amounts to their market value + on the report end date, using the most recent applicable market prices, + when known. Specifically, when there is a market price (P directive) + for the amount's commodity, dated on or before the report end date (see + hledger -> Report start & end date), the amount will be converted to + the price's commodity. If multiple applicable prices are defined, the + latest-dated one is used (and if dates are equal, the one last parsed). + + For example: + + # one euro is worth this many dollars from nov 1 + P 2016/11/01 $1.10 + + # purchase some euros on nov 3 + 2016/11/3 + assets:euros 100 + assets:checking + + # the euro is worth fewer dollars by dec 21 + P 2016/12/21 $1.03 + + How many euros do I have ? + + $ hledger -f t.j bal euros + 100 assets:euros + + What are they worth on nov 3 ? (no report end date specified, defaults + to the last date in the journal) + + $ hledger -f t.j bal euros -V + $110.00 assets:euros + + What are they worth on dec 21 ? + + $ hledger -f t.j bal euros -V -e 2016/12/21 + $103.00 assets:euros + + Currently, hledger's -V only uses market prices recorded with P direc- + tives, not transaction prices (unlike Ledger). + + Using -B and -V together is allowed. + Regular expressions hledger uses regular expressions in a number of places: @@ -576,6 +623,8 @@ o any of the account terms AND + o any of the status terms AND + o all the other terms. The print command: show transactions which @@ -635,14 +684,13 @@ real:, real:0 match real or virtual postings respectively - status:*, status:!, status: - match cleared, pending, or uncleared/pending transactions - respectively + status:, status:!, status:* + match unmarked, pending, or cleared transactions respectively tag:REGEX[=REGEX] - match by tag name, and optionally also by tag value. Note a - tag: query is considered to match a transaction if it matches - any of the postings. Also remember that postings inherit the + match by tag name, and optionally also by tag value. Note a + tag: query is considered to match a transaction if it matches + any of the postings. Also remember that postings inherit the tags of their parent transaction. not: before any of the above negates the match. @@ -650,24 +698,24 @@ inacct:ACCTNAME a special term used automatically when you click an account name in hledger-web, specifying the account register we are currently - in (selects the transactions of that account and how to show - them, can be filtered further with acct etc). Not supported + in (selects the transactions of that account and how to show + them, can be filtered further with acct etc). Not supported elsewhere in hledger. Some of these can also be expressed as command-line options (eg depth:2 - is equivalent to --depth 2). Generally you can mix options and query - arguments, and the resulting query will be their intersection (perhaps + is equivalent to --depth 2). Generally you can mix options and query + arguments, and the resulting query will be their intersection (perhaps excluding the -p/--period option). COMMANDS - hledger provides a number of subcommands; hledger with no arguments + hledger provides a number of subcommands; hledger with no arguments shows a list. If you install additional hledger-* packages, or if you put programs or - scripts named hledger-NAME in your PATH, these will also be listed as + scripts named hledger-NAME in your PATH, these will also be listed as subcommands. - Run a subcommand by writing its name as first argument (eg + Run a subcommand by writing its name as first argument (eg hledger incomestatement). You can also write any unambiguous prefix of a command name (hledger inc), or one of the standard short aliases dis- played in the command list (hledger is). @@ -682,14 +730,14 @@ --drop=N in flat mode: omit N leading account name parts - This command lists all account names that are in use (ie, all the - accounts which have at least one transaction posting to them). With + This command lists all account names that are in use (ie, all the + accounts which have at least one transaction posting to them). With query arguments, only matched account names are shown. - It shows a flat list by default. With --tree, it uses indentation to + It shows a flat list by default. With --tree, it uses indentation to show the account hierarchy. - In flat mode you can add --drop N to omit the first few account name + In flat mode you can add --drop N to omit the first few account name components. Examples: @@ -732,8 +780,8 @@ activity Show an ascii barchart of posting counts per interval. - The activity command displays an ascii histogram showing transaction - counts by day, week, month or other reporting interval (by day is the + The activity command displays an ascii histogram showing transaction + counts by day, week, month or other reporting interval (by day is the default). With query arguments, it counts only matched transactions. $ hledger activity --quarterly @@ -746,24 +794,24 @@ Prompt for transactions and add them to the journal. --no-new-accounts - don't allow creating new accounts; helps prevent typos when + don't allow creating new accounts; helps prevent typos when entering account names - Many hledger users edit their journals directly with a text editor, or - generate them from CSV. For more interactive data entry, there is the - add command, which prompts interactively on the console for new trans- - actions, and appends them to the journal file (if there are multiple + Many hledger users edit their journals directly with a text editor, or + generate them from CSV. For more interactive data entry, there is the + add command, which prompts interactively on the console for new trans- + actions, and appends them to the journal file (if there are multiple -f FILE options, the first file is used.) Existing transactions are not - changed. This is the only hledger command that writes to the journal + changed. This is the only hledger command that writes to the journal file. To use it, just run hledger add and follow the prompts. You can add as - many transactions as you like; when you are finished, enter . or press + many transactions as you like; when you are finished, enter . or press control-d or control-c to exit. Features: - o add tries to provide useful defaults, using the most similar recent + o add tries to provide useful defaults, using the most similar recent transaction (by description) as a template. o You can also set the initial defaults with command line arguments. @@ -771,20 +819,20 @@ o Readline-style edit keys can be used during data entry. o The tab key will auto-complete whenever possible - accounts, descrip- - tions, dates (yesterday, today, tomorrow). If the input area is + tions, dates (yesterday, today, tomorrow). If the input area is empty, it will insert the default value. - o If the journal defines a default commodity, it will be added to any + o If the journal defines a default commodity, it will be added to any bare numbers entered. o A parenthesised transaction code may be entered following a date. o Comments and tags may be entered following a description or amount. - o If you make a mistake, enter < at any prompt to restart the transac- + o If you make a mistake, enter < at any prompt to restart the transac- tion. - o Input prompts are displayed in a different colour when the terminal + o Input prompts are displayed in a different colour when the terminal supports it. Example (see the tutorial for a detailed explanation): @@ -821,7 +869,7 @@ show balance change in each period (default) --cumulative - show balance change accumulated across periods (in multicolumn + show balance change accumulated across periods (in multicolumn reports) -H --historical @@ -856,14 +904,14 @@ select the output format. Supported formats: txt, csv. -o FILE --output-file=FILE - write output to FILE. A file extension matching one of the + write output to FILE. A file extension matching one of the above formats selects that format. --pretty-tables Use unicode to display prettier tables. - The balance command displays accounts and balances. It is hledger's - most featureful and most useful command. + The balance command displays accounts and balances. It is hledger's + most featureful and versatile command. $ hledger balance $-1 assets @@ -879,16 +927,17 @@ -------------------- 0 - More precisely, the balance command shows the change to each account's + More precisely, the balance command shows the change to each account's balance caused by all (matched) postings. In the common case where you - do not filter by date and your journal sets the correct opening bal- + do not filter by date and your journal sets the correct opening bal- ances, this is the same as the account's ending balance. - By default, accounts are displayed hierarchically, with subaccounts + By default, accounts are displayed hierarchically, with subaccounts indented below their parent. "Boring" accounts, which contain a single interesting subaccount and no balance of their own, are elided into the - following line for more compact output. (Use --no-elide to prevent - this.) + following line for more compact output. (Use --no-elide to prevent + this. Eliding of boring accounts is not yet supported in multicolumn + reports.) Each account's balance is the "inclusive" balance - it includes the balances of any subaccounts. @@ -1022,51 +1071,8 @@ # Average is rounded to the dollar here since all journal amounts are - Market value - The -V/--value flag converts the reported amounts to their market value - on the report end date, using the most recent applicable market prices, - when known. Specifically, when there is a market price (P directive) - for the amount's commodity, dated on or before the report end date (see - hledger -> Report start & end date), the amount will be converted to - the price's commodity. If multiple applicable prices are defined, the - latest-dated one is used (and if dates are equal, the one last parsed). - - For example: - - # one euro is worth this many dollars from nov 1 - P 2016/11/01 $1.10 - - # purchase some euros on nov 3 - 2016/11/3 - assets:euros 100 - assets:checking - - # the euro is worth fewer dollars by dec 21 - P 2016/12/21 $1.03 - - How many euros do I have ? - - $ hledger -f t.j bal euros - 100 assets:euros - - What are they worth on nov 3 ? (no report end date specified, defaults - to the last date in the journal) - - $ hledger -f t.j bal euros -V - $110.00 assets:euros - - What are they worth on dec 21 ? - - $ hledger -f t.j bal euros -V -e 2016/12/21 - $103.00 assets:euros - - Currently, hledger's -V only uses market prices recorded with P direc- - tives, not transaction prices (unlike Ledger). - - Using -B and -V together is allowed. - Custom balance output - In simple (non-multi-column) balance reports, you can customise the + In simple (non-multi-column) balance reports, you can customise the output with --format FMT: $ hledger balance --format "%20(account) %12(total)" @@ -1084,7 +1090,7 @@ 0 The FMT format string (plus a newline) specifies the formatting applied - to each account/balance pair. It may contain any suitable text, with + to each account/balance pair. It may contain any suitable text, with data fields interpolated like so: %[MIN][.MAX](FIELDNAME) @@ -1095,14 +1101,14 @@ o FIELDNAME must be enclosed in parentheses, and can be one of: - o depth_spacer - a number of spaces equal to the account's depth, or + o depth_spacer - a number of spaces equal to the account's depth, or if MIN is specified, MIN * depth spaces. o account - the account's name o total - the account's balance/posted total, right justified - Also, FMT can begin with an optional prefix to control how multi-com- + Also, FMT can begin with an optional prefix to control how multi-com- modity amounts are rendered: o %_ - render on multiple lines, bottom-aligned (the default) @@ -1111,7 +1117,7 @@ o %, - render on one line, comma-separated - There are some quirks. Eg in one-line mode, %(depth_spacer) has no + There are some quirks. Eg in one-line mode, %(depth_spacer) has no effect, instead %(account) has indentation built in. Experimentation may be needed to get pleasing results. @@ -1119,19 +1125,26 @@ o %(total) - the account's total - o %-20.20(account) - the account's name, left justified, padded to 20 + o %-20.20(account) - the account's name, left justified, padded to 20 characters and clipped at 20 characters - o %,%-50(account) %25(total) - account name padded to 50 characters, - total padded to 20 characters, with multiple commodities rendered on + o %,%-50(account) %25(total) - account name padded to 50 characters, + total padded to 20 characters, with multiple commodities rendered on one line - o %20(total) %2(depth_spacer)%-(account) - the default format for the + o %20(total) %2(depth_spacer)%-(account) - the default format for the single-column balance report + Colour support + The balance command shows negative amounts in red, if: + + o the TERM environment variable is not set to dumb + + o the output is not being redirected or piped anywhere + Output destination - The balance, print, register and stats commands can write their output - to a destination other than the console. This is controlled by the + The balance, print, register and stats commands can write their output + to a destination other than the console. This is controlled by the -o/--output-file option. $ hledger balance -o - # write to stdout (the default) @@ -1139,8 +1152,8 @@ CSV output The balance, print and register commands can write their output as CSV. - This is useful for exporting data to other applications, eg to make - charts in a spreadsheet. This is controlled by the -O/--output-format + This is useful for exporting data to other applications, eg to make + charts in a spreadsheet. This is controlled by the -O/--output-format option, or by specifying a .csv file extension with -o/--output-file. $ hledger balance -O csv # write CSV to stdout @@ -1154,7 +1167,7 @@ balances --cumulative - show balance change accumulated across periods (in multicolumn + show balance change accumulated across periods (in multicolumn reports), instead of historical ending balances -H --historical @@ -1185,8 +1198,8 @@ --format=LINEFORMAT in single-column balance reports: use this custom line format - This command displays a simple balance sheet. It currently assumes - that you have top-level accounts named asset and liability (plural + This command displays a simple balance sheet. It currently assumes + that you have top-level accounts named asset and liability (plural forms also allowed.) $ hledger balancesheet @@ -1209,9 +1222,9 @@ 0 With a reporting interval, multiple columns will be shown, one for each - report period. As with multicolumn balance reports, you can alter the - report mode with --change/--cumulative/--historical. Normally bal- - ancesheet shows historical ending balances, which is what you need for + report period. As with multicolumn balance reports, you can alter the + report mode with --change/--cumulative/--historical. Normally bal- + ancesheet shows historical ending balances, which is what you need for a balance sheet; note this means it ignores report begin dates. cashflow @@ -1221,7 +1234,7 @@ show balance change in each period (default) --cumulative - show balance change accumulated across periods (in multicolumn + show balance change accumulated across periods (in multicolumn reports), instead of changes during periods -H --historical @@ -1252,9 +1265,9 @@ --format=LINEFORMAT in single-column balance reports: use this custom line format - This command displays a simple cashflow statement It shows the change - in all "cash" (ie, liquid assets) accounts for the period. It cur- - rently assumes that cash accounts are under a top-level account named + This command displays a simple cashflow statement It shows the change + in all "cash" (ie, liquid assets) accounts for the period. It cur- + rently assumes that cash accounts are under a top-level account named asset and do not contain receivable or A/R (plural forms also allowed.) $ hledger cashflow @@ -1272,18 +1285,18 @@ $-1 With a reporting interval, multiple columns will be shown, one for each - report period. Normally cashflow shows changes in assets per period, - though as with multicolumn balance reports you can alter the report + report period. Normally cashflow shows changes in assets per period, + though as with multicolumn balance reports you can alter the report mode with --change/--cumulative/--historical. help Show any of the hledger manuals. - The help command displays any of the main hledger man pages. (Unlike - hledger --help, which displays only the hledger man page.) Run it with - no arguments to list available topics (their names are shortened for - easier typing), and run hledger help TOPIC to select one. The output - is similar to a man page, but fixed width. It may be long, so you may + The help command displays any of the main hledger man pages. (Unlike + hledger --help, which displays only the hledger man page.) Run it with + no arguments to list available topics (their names are shortened for + easier typing), and run hledger help TOPIC to select one. The output + is similar to a man page, but fixed width. It may be long, so you may wish to pipe it into a pager. See also info and man. $ hledger help @@ -1311,7 +1324,7 @@ show balance change in each period (default) --cumulative - show balance change accumulated across periods (in multicolumn + show balance change accumulated across periods (in multicolumn reports), instead of changes during periods -H --historical @@ -1342,8 +1355,8 @@ --format=LINEFORMAT in single-column balance reports: use this custom line format - This command displays a simple income statement. It currently assumes - that you have top-level accounts named income (or revenue) and expense + This command displays a simple income statement. It currently assumes + that you have top-level accounts named income (or revenue) and expense (plural forms also allowed.) $ hledger incomestatement @@ -1368,30 +1381,30 @@ 0 With a reporting interval, multiple columns will be shown, one for each - report period. Normally incomestatement shows revenues/expenses per - period, though as with multicolumn balance reports you can alter the + report period. Normally incomestatement shows revenues/expenses per + period, though as with multicolumn balance reports you can alter the report mode with --change/--cumulative/--historical. info Show any of the hledger manuals using info. - The info command displays any of the hledger reference manuals using - the info hypertextual documentation viewer. This can be a very effi- - cient way to browse large manuals. It requires the "info" program to + The info command displays any of the hledger reference manuals using + the info hypertextual documentation viewer. This can be a very effi- + cient way to browse large manuals. It requires the "info" program to be available in your PATH. - As with help, run it with no arguments to list available topics (manu- + As with help, run it with no arguments to list available topics (manu- als). man Show any of the hledger manuals using man. - The man command displays any of the hledger reference manuals using - man, the standard documentation viewer on unix systems. This will fit - the text to your terminal width, and probably invoke a pager automati- + The man command displays any of the hledger reference manuals using + man, the standard documentation viewer on unix systems. This will fit + the text to your terminal width, and probably invoke a pager automati- cally. It requires the "man" program to be available in your PATH. - As with help, run it with no arguments to list available topics (manu- + As with help, run it with no arguments to list available topics (manu- als). print @@ -1401,14 +1414,14 @@ show all amounts explicitly -m STR --match=STR - show the transaction whose description is most similar to STR, + show the transaction whose description is most similar to STR, and is most recent -O FMT --output-format=FMT select the output format. Supported formats: txt, csv. -o FILE --output-file=FILE - write output to FILE. A file extension matching one of the + write output to FILE. A file extension matching one of the above formats selects that format. $ hledger print @@ -1436,23 +1449,23 @@ The print command displays full journal entries (transactions) from the journal file, tidily formatted. - As of hledger 1.2, print's output is always a valid hledger journal. - However it may not preserve all original content, eg it does not print + As of hledger 1.2, print's output is always a valid hledger journal. + However it may not preserve all original content, eg it does not print directives or inter-transaction comments. - Normally, transactions' implicit/explicit amount style is preserved: - when an amount is omitted in the journal, it will be omitted in the - output. You can use the -x/--explicit flag to make all amounts - explicit, which can be useful for troubleshooting or for making your - journal more readable and robust against data entry errors. Note, in - this mode postings with a multi-commodity amount (possible with an - implicit amount in a multi-commodity transaction) will be split into + Normally, transactions' implicit/explicit amount style is preserved: + when an amount is omitted in the journal, it will be omitted in the + output. You can use the -x/--explicit flag to make all amounts + explicit, which can be useful for troubleshooting or for making your + journal more readable and robust against data entry errors. Note, in + this mode postings with a multi-commodity amount (possible with an + implicit amount in a multi-commodity transaction) will be split into multiple single-commodity postings, for valid journal output. - With -B/--cost, amounts with transaction prices are converted to cost + With -B/--cost, amounts with transaction prices are converted to cost (using the transaction price). - The print command also supports output destination and CSV output. + The print command also supports output destination and CSV output. Here's an example of print's CSV output: $ hledger print -Ocsv @@ -1469,20 +1482,20 @@ "5","2008/12/31","","*","","pay off","","liabilities:debts","1","$","","1","","" "5","2008/12/31","","*","","pay off","","assets:bank:checking","-1","$","1","","","" - o There is one CSV record per posting, with the parent transaction's + o There is one CSV record per posting, with the parent transaction's fields repeated. o The "txnidx" (transaction index) field shows which postings belong to - the same transaction. (This number might change if transactions are - reordered within the file, files are parsed/included in a different + the same transaction. (This number might change if transactions are + reordered within the file, files are parsed/included in a different order, etc.) - o The amount is separated into "commodity" (the symbol) and "amount" + o The amount is separated into "commodity" (the symbol) and "amount" (numeric quantity) fields. o The numeric amount is repeated in either the "credit" or "debit" col- - umn, for convenience. (Those names are not accurate in the account- - ing sense; it just puts negative amounts under credit and zero or + umn, for convenience. (Those names are not accurate in the account- + ing sense; it just puts negative amounts under credit and zero or greater amounts under debit.) register @@ -1492,7 +1505,7 @@ show running total from report start date (default) -H --historical - show historical running total/balance (includes postings before + show historical running total/balance (includes postings before report start date) -A --average @@ -1503,18 +1516,18 @@ show postings' siblings instead -w N --width=N - set output width (default: terminal width or COLUMNS. -wN,M + set output width (default: terminal width or COLUMNS. -wN,M sets description width as well) -O FMT --output-format=FMT select the output format. Supported formats: txt, csv. -o FILE --output-file=FILE - write output to FILE. A file extension matching one of the + write output to FILE. A file extension matching one of the above formats selects that format. The register command displays postings, one per line, and their running - total. This is typically used with a query selecting a particular + total. This is typically used with a query selecting a particular account, to see that account's activity: $ hledger register checking @@ -1523,8 +1536,8 @@ 2008/06/02 save assets:bank:checking $-1 $1 2008/12/31 pay off assets:bank:checking $-1 0 - The --historical/-H flag adds the balance from any undisplayed prior - postings to the running total. This is useful when you want to see + The --historical/-H flag adds the balance from any undisplayed prior + postings to the running total. This is useful when you want to see only recent activity, with a historically accurate running balance: $ hledger register checking -b 2008/6 --historical @@ -1534,23 +1547,23 @@ The --depth option limits the amount of sub-account detail displayed. - The --average/-A flag shows the running average posting amount instead + The --average/-A flag shows the running average posting amount instead of the running total (so, the final number displayed is the average for - the whole report period). This flag implies --empty (see below). It - is affected by --historical. It works best when showing just one + the whole report period). This flag implies --empty (see below). It + is affected by --historical. It works best when showing just one account and one commodity. - The --related/-r flag shows the other postings in the transactions of + The --related/-r flag shows the other postings in the transactions of the postings which would normally be shown. - With a reporting interval, register shows summary postings, one per + With a reporting interval, register shows summary postings, one per interval, aggregating the postings to each account: $ hledger register --monthly income 2008/01 income:salary $-1 $-1 2008/06 income:gifts $-1 $-2 - Periods with no activity, and summary postings with a zero amount, are + Periods with no activity, and summary postings with a zero amount, are not shown by default; use the --empty/-E flag to see them: $ hledger register --monthly income -E @@ -1567,7 +1580,7 @@ 2008/11 0 $-2 2008/12 0 $-2 - Often, you'll want to see just one line per interval. The --depth + Often, you'll want to see just one line per interval. The --depth option helps with this, causing subaccounts to be aggregated: $ hledger register --monthly assets --depth 1h @@ -1575,19 +1588,19 @@ 2008/06 assets $-1 0 2008/12 assets $-1 $-1 - Note when using report intervals, if you specify start/end dates these - will be adjusted outward if necessary to contain a whole number of - intervals. This ensures that the first and last intervals are full + Note when using report intervals, if you specify start/end dates these + will be adjusted outward if necessary to contain a whole number of + intervals. This ensures that the first and last intervals are full length and comparable to the others in the report. Custom register output - register uses the full terminal width by default, except on windows. - You can override this by setting the COLUMNS environment variable (not + register uses the full terminal width by default, except on windows. + You can override this by setting the COLUMNS environment variable (not a bash shell variable) or by using the --width/-w option. - The description and account columns normally share the space equally - (about half of (width - 40) each). You can adjust this by adding a - description width as part of --width's argument, comma-separated: + The description and account columns normally share the space equally + (about half of (width - 40) each). You can adjust this by adding a + description width as part of --width's argument, comma-separated: --width W,D . Here's a diagram: <--------------------------------- width (W) ----------------------------------> @@ -1603,14 +1616,14 @@ $ hledger reg -w 100,40 # set overall width 100, description width 40 $ hledger reg -w $COLUMNS,40 # use terminal width, and set description width - The register command also supports the -o/--output-file and -O/--out- + The register command also supports the -o/--output-file and -O/--out- put-format options for controlling output destination and CSV output. stats Show some journal statistics. -o FILE --output-file=FILE - write output to FILE. A file extension matching one of the + write output to FILE. A file extension matching one of the above formats selects that format. $ hledger stats @@ -1625,8 +1638,8 @@ Accounts : 8 (depth 3) Commodities : 1 ($) - The stats command displays summary information for the whole journal, - or a matched part of it. With a reporting interval, it shows a report + The stats command displays summary information for the whole journal, + or a matched part of it. With a reporting interval, it shows a report for each report period. The stats command also supports -o/--output-file for controlling output @@ -1638,34 +1651,34 @@ $ hledger test Cases: 74 Tried: 74 Errors: 0 Failures: 0 - This command runs hledger's built-in unit tests and displays a quick + This command runs hledger's built-in unit tests and displays a quick report. With a regular expression argument, it selects only tests with matching names. It's mainly used in development, but it's also nice to be able to check your hledger executable for smoke at any time. ADD-ON COMMANDS - hledger also searches for external add-on commands, and will include + hledger also searches for external add-on commands, and will include these in the commands list. These are programs or scripts in your PATH - whose name starts with hledger- and ends with a recognised file exten- + whose name starts with hledger- and ends with a recognised file exten- sion (currently: no extension, bat,com,exe, hs,lhs,pl,py,rb,rkt,sh). - Add-ons can be invoked like any hledger command, but there are a few + Add-ons can be invoked like any hledger command, but there are a few things to be aware of. Eg if the hledger-web add-on is installed, o hledger -h web shows hledger's help, while hledger web -h shows hledger-web's help. - o Flags specific to the add-on must have a preceding -- to hide them - from hledger. So hledger web --serve --port 9000 will be rejected; + o Flags specific to the add-on must have a preceding -- to hide them + from hledger. So hledger web --serve --port 9000 will be rejected; you must use hledger web -- --serve --port 9000. - o You can always run add-ons directly if preferred: + o You can always run add-ons directly if preferred: hledger-web --serve --port 9000. - Add-ons are a relatively easy way to add local features or experiment - with new ideas. They can be written in any language, but haskell - scripts have a big advantage: they can use the same hledger (and - haskell) library functions that built-in commands do, for command-line + Add-ons are a relatively easy way to add local features or experiment + with new ideas. They can be written in any language, but haskell + scripts have a big advantage: they can use the same hledger (and + haskell) library functions that built-in commands do, for command-line options, journal parsing, reporting, etc. Here are some hledger add-ons available: @@ -1683,7 +1696,7 @@ hledger-web provides a simple web interface. Third party add-ons - These are maintained separately, and usually updated shortly after a + These are maintained separately, and usually updated shortly after a hledger release. diff @@ -1691,7 +1704,7 @@ journal file and another. iadd - hledger-iadd is a curses-style, more interactive replacement for the + hledger-iadd is a curses-style, more interactive replacement for the add command. interest @@ -1699,19 +1712,19 @@ ing to various schemes. irr - hledger-irr calculates the internal rate of return of an investment + hledger-irr calculates the internal rate of return of an investment account. Experimental add-ons - These are available in source form in the hledger repo's bin/ direc- + These are available in source form in the hledger repo's bin/ direc- tory; installing them is pretty easy. They may be less mature and doc- - umented than built-in commands. Reading and tweaking these is a good + umented than built-in commands. Reading and tweaking these is a good way to start making your own! autosync hledger-autosync is a symbolic link for easily running ledger-autosync, - if installed. ledger-autosync does deduplicating conversion of OFX - data and some CSV formats, and can also download the data if your bank + if installed. ledger-autosync does deduplicating conversion of OFX + data and some CSV formats, and can also download the data if your bank offers OFX Direct Connect. budget @@ -1727,18 +1740,18 @@ hledger-check-dates.hs checks that journal entries are ordered by date. check-dupes - hledger-check-dupes.hs checks for account names sharing the same leaf + hledger-check-dupes.hs checks for account names sharing the same leaf name. equity - hledger-equity.hs prints balance-resetting transactions, useful for + hledger-equity.hs prints balance-resetting transactions, useful for bringing account balances across file boundaries. prices hledger-prices.hs prints all prices from the journal. print-unique - hledger-print-unique.hs prints transactions which do not reuse an + hledger-print-unique.hs prints transactions which do not reuse an already-seen description. register-match @@ -1750,21 +1763,21 @@ tions. ENVIRONMENT - COLUMNS The screen width used by the register command. Default: the + COLUMNS The screen width used by the register command. Default: the full terminal width. LEDGER_FILE The journal file path when not specified with -f. Default: - ~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour- + ~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour- nal). FILES - Reads data from one or more files in hledger journal, timeclock, time- - dot, or CSV format specified with -f, or $LEDGER_FILE, or - $HOME/.hledger.journal (on windows, perhaps + Reads data from one or more files in hledger journal, timeclock, time- + dot, or CSV format specified with -f, or $LEDGER_FILE, or + $HOME/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.journal). BUGS - The need to precede addon command options with -- when invoked from + The need to precede addon command options with -- when invoked from hledger is awkward. When input data contains non-ascii characters, a suitable system locale @@ -1777,33 +1790,33 @@ In a Cygwin/MSYS/Mintty window, the tab key is not supported in hledger add. - Not all of Ledger's journal file syntax is supported. See file format + Not all of Ledger's journal file syntax is supported. See file format differences. - On large data files, hledger is slower and uses more memory than + On large data files, hledger is slower and uses more memory than Ledger. TROUBLESHOOTING - Here are some issues you might encounter when you run hledger (and - remember you can also seek help from the IRC channel, mail list or bug + Here are some issues you might encounter when you run hledger (and + remember you can also seek help from the IRC channel, mail list or bug tracker): Successfully installed, but "No command 'hledger' found" stack and cabal install binaries into a special directory, which should - be added to your PATH environment variable. Eg on unix-like systems, + be added to your PATH environment variable. Eg on unix-like systems, that is ~/.local/bin and ~/.cabal/bin respectively. I set a custom LEDGER_FILE, but hledger is still using the default file - LEDGER_FILE should be a real environment variable, not just a shell - variable. The command env | grep LEDGER_FILE should show it. You may + LEDGER_FILE should be a real environment variable, not just a shell + variable. The command env | grep LEDGER_FILE should show it. You may need to use export. Here's an explanation. - "Illegal byte sequence" or "Invalid or incomplete multibyte or wide + "Illegal byte sequence" or "Invalid or incomplete multibyte or wide character" errors In order to handle non-ascii letters and symbols (like ), hledger needs an appropriate locale. This is usually configured system-wide; you can also configure it temporarily. The locale may need to be one that sup- - ports UTF-8, if you built hledger with GHC < 7.2 (or possibly always, + ports UTF-8, if you built hledger with GHC < 7.2 (or possibly always, I'm not sure yet). Here's an example of setting the locale temporarily, on ubuntu @@ -1822,7 +1835,7 @@ $ echo "export LANG=en_US.UTF-8" >>~/.bash_profile $ bash --login - If we preferred to use eg fr_FR.utf8, we might have to install that + If we preferred to use eg fr_FR.utf8, we might have to install that first: $ apt-get install language-pack-fr @@ -1843,7 +1856,7 @@ 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) @@ -1857,7 +1870,7 @@ 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) @@ -1865,4 +1878,4 @@ -hledger 1.2 March 2017 hledger(1) +hledger 1.3 June 2017 hledger(1) diff --git a/doc/other/hledger-api.1 b/doc/other/hledger-api.1 --- a/doc/other/hledger-api.1 +++ b/doc/other/hledger-api.1 @@ -1,5 +1,5 @@ -.TH "hledger\-api" "1" "March 2017" "hledger\-api 1.2" "hledger User Manuals" +.TH "hledger\-api" "1" "June 2017" "hledger\-api 1.3" "hledger User Manuals" diff --git a/doc/other/hledger-api.1.info b/doc/other/hledger-api.1.info --- a/doc/other/hledger-api.1.info +++ b/doc/other/hledger-api.1.info @@ -3,7 +3,7 @@  File: hledger-api.1.info, Node: Top, Next: OPTIONS, Up: (dir) -hledger-api(1) hledger-api 1.2 +hledger-api(1) hledger-api 1.3 ****************************** hledger-api is a simple web API server, intended to support client-side diff --git a/doc/other/hledger-api.1.txt b/doc/other/hledger-api.1.txt --- a/doc/other/hledger-api.1.txt +++ b/doc/other/hledger-api.1.txt @@ -107,4 +107,4 @@ -hledger-api 1.2 March 2017 hledger-api(1) +hledger-api 1.3 June 2017 hledger-api(1) diff --git a/doc/other/hledger-ui.1 b/doc/other/hledger-ui.1 --- a/doc/other/hledger-ui.1 +++ b/doc/other/hledger-ui.1 @@ -1,5 +1,5 @@ -.TH "hledger\-ui" "1" "March 2017" "hledger\-ui 1.2" "hledger User Manuals" +.TH "hledger\-ui" "1" "June 2017" "hledger\-ui 1.3" "hledger User Manuals" @@ -146,18 +146,18 @@ .RS .RE .TP -.B \f[C]\-C\ \-\-cleared\f[] -include only cleared postings/txns +.B \f[C]\-U\ \-\-unmarked\f[] +include only unmarked postings/txns (can combine with \-P or \-C) .RS .RE .TP -.B \f[C]\-\-pending\f[] +.B \f[C]\-P\ \-\-pending\f[] include only pending postings/txns .RS .RE .TP -.B \f[C]\-U\ \-\-uncleared\f[] -include only uncleared (and pending) postings/txns +.B \f[C]\-C\ \-\-cleared\f[] +include only cleared postings/txns .RS .RE .TP @@ -232,8 +232,9 @@ deeper, \f[C]left\f[] returns to the previous screen, \f[C]up\f[]/\f[C]down\f[]/\f[C]page\ up\f[]/\f[C]page\ down\f[]/\f[C]home\f[]/\f[C]end\f[] move up and down through lists. -Vi\-style \f[C]h\f[]/\f[C]j\f[]/\f[C]k\f[]/\f[C]l\f[] movement keys are -also supported. +Vi\-style (\f[C]h\f[]/\f[C]j\f[]/\f[C]k\f[]/\f[C]l\f[]) and Emacs\-style +(\f[C]CTRL\-p\f[]/\f[C]CTRL\-n\f[]/\f[C]CTRL\-f\f[]/\f[C]CTRL\-b\f[]) +movement keys are also supported. A tip: movement speed is limited by your keyboard repeat rate, to move faster you may want to adjust it. (If you\[aq]re on a mac, the Karabiner app is one way to do that.) @@ -255,13 +256,17 @@ While editing the query, you can use CTRL\-a/e/d/k, BS, cursor keys; press \f[C]ENTER\f[] to set it, or \f[C]ESCAPE\f[]to cancel. There are also keys for quickly adjusting some common filters like -account depth and cleared/uncleared (see below). +account depth and transaction status (see below). \f[C]BACKSPACE\f[] or \f[C]DELETE\f[] removes all filters, showing all transactions. .PP \f[C]ESCAPE\f[] removes all filters and jumps back to the top screen. Or, it cancels a minibuffer edit or help dialog in progress. .PP +\f[C]CTRL\-l\f[] redraws the screen and centers the selection if +possible (selections near the top won\[aq]t be centered, since we +don\[aq]t scroll above the top). +.PP \f[C]g\f[] reloads from the data file(s) and updates the current screen and any previous screens. (With large files, this could cause a noticeable pause.) @@ -322,10 +327,13 @@ they show the change in balance during the report period. They are more useful eg when viewing a time log. .PP -\f[C]C\f[] toggles cleared mode, in which uncleared transactions and -postings are not shown. -\f[C]U\f[] toggles uncleared mode, in which only uncleared -transactions/postings are shown. +\f[C]U\f[] toggles filtering by unmarked status, including or excluding +unmarked postings in the balances. +Similarly, \f[C]P\f[] toggles pending postings, and \f[C]C\f[] toggles +cleared postings. +(By default, balances include all postings; if you activate one or two +status filters, only those postings are included; and if you activate +all three, the filter is removed.) .PP \f[C]R\f[] toggles real mode, in which virtual postings are ignored. .PP @@ -367,10 +375,13 @@ for the period balance shown on the accounts screen. As on the accounts screen, this can be toggled with \f[C]F\f[]. .PP -\f[C]C\f[] toggles cleared mode, in which uncleared transactions and -postings are not shown. -\f[C]U\f[] toggles uncleared mode, in which only uncleared -transactions/postings are shown. +\f[C]U\f[] toggles filtering by unmarked status, showing or hiding +unmarked transactions. +Similarly, \f[C]P\f[] toggles pending transactions, and \f[C]C\f[] +toggles cleared transactions. +(By default, transactions with all statuses are shown; if you activate +one or two status filters, only those transactions are shown; and if you +activate all three, the filter is removed.)q .PP \f[C]R\f[] toggles real mode, in which virtual postings are ignored. .PP diff --git a/doc/other/hledger-ui.1.info b/doc/other/hledger-ui.1.info --- a/doc/other/hledger-ui.1.info +++ b/doc/other/hledger-ui.1.info @@ -3,7 +3,7 @@  File: hledger-ui.1.info, Node: Top, Next: OPTIONS, Up: (dir) -hledger-ui(1) hledger-ui 1.2 +hledger-ui(1) hledger-ui 1.3 **************************** hledger-ui is hledger's curses-style interface, providing an efficient @@ -104,15 +104,15 @@ '--date2' show, and match with -b/-e/-p/date:, secondary dates instead -'-C --cleared' +'-U --unmarked' - include only cleared postings/txns -'--pending' + include only unmarked postings/txns (can combine with -P or -C) +'-P --pending' include only pending postings/txns -'-U --uncleared' +'-C --cleared' - include only uncleared (and pending) postings/txns + include only cleared postings/txns '-R --real' include only non-virtual postings @@ -167,10 +167,10 @@ The cursor keys navigate: 'right' (or 'enter') goes deeper, 'left' returns to the previous screen, 'up'/'down'/'page up'/'page down'/'home'/'end' move up and down through lists. Vi-style -'h'/'j'/'k'/'l' movement keys are also supported. A tip: movement speed -is limited by your keyboard repeat rate, to move faster you may want to -adjust it. (If you're on a mac, the Karabiner app is one way to do -that.) +('h'/'j'/'k'/'l') and Emacs-style ('CTRL-p'/'CTRL-n'/'CTRL-f'/'CTRL-b') +movement keys are also supported. A tip: movement speed is limited by +your keyboard repeat rate, to move faster you may want to adjust it. +(If you're on a mac, the Karabiner app is one way to do that.) With shift pressed, the cursor keys adjust the report period, limiting the transactions to be shown (by default, all are shown). @@ -186,13 +186,17 @@ using the same query terms as in hledger and hledger-web. While editing the query, you can use CTRL-a/e/d/k, BS, cursor keys; press 'ENTER' to set it, or 'ESCAPE'to cancel. There are also keys for quickly adjusting -some common filters like account depth and cleared/uncleared (see +some common filters like account depth and transaction status (see below). 'BACKSPACE' or 'DELETE' removes all filters, showing all transactions. 'ESCAPE' removes all filters and jumps back to the top screen. Or, it cancels a minibuffer edit or help dialog in progress. + 'CTRL-l' redraws the screen and centers the selection if possible +(selections near the top won't be centered, since we don't scroll above +the top). + 'g' reloads from the data file(s) and updates the current screen and any previous screens. (With large files, this could cause a noticeable pause.) @@ -260,9 +264,12 @@ before the report start date, so they show the change in balance during the report period. They are more useful eg when viewing a time log. - 'C' toggles cleared mode, in which uncleared transactions and -postings are not shown. 'U' toggles uncleared mode, in which only -uncleared transactions/postings are shown. + 'U' toggles filtering by unmarked status, including or excluding +unmarked postings in the balances. Similarly, 'P' toggles pending +postings, and 'C' toggles cleared postings. (By default, balances +include all postings; if you activate one or two status filters, only +those postings are included; and if you activate all three, the filter +is removed.) 'R' toggles real mode, in which virtual postings are ignored. @@ -304,9 +311,12 @@ responsible for the period balance shown on the accounts screen. As on the accounts screen, this can be toggled with 'F'. - 'C' toggles cleared mode, in which uncleared transactions and -postings are not shown. 'U' toggles uncleared mode, in which only -uncleared transactions/postings are shown. + 'U' toggles filtering by unmarked status, showing or hiding unmarked +transactions. Similarly, 'P' toggles pending transactions, and 'C' +toggles cleared transactions. (By default, transactions with all +statuses are shown; if you activate one or two status filters, only +those transactions are shown; and if you activate all three, the filter +is removed.)q 'R' toggles real mode, in which virtual postings are ignored. @@ -357,17 +367,17 @@ Node: Top73 Node: OPTIONS825 Ref: #options924 -Node: KEYS3650 -Ref: #keys3747 -Node: SCREENS6335 -Ref: #screens6422 -Node: Accounts screen6512 -Ref: #accounts-screen6642 -Node: Register screen8691 -Ref: #register-screen8848 -Node: Transaction screen10737 -Ref: #transaction-screen10897 -Node: Error screen11767 -Ref: #error-screen11891 +Node: KEYS3665 +Ref: #keys3762 +Node: SCREENS6558 +Ref: #screens6645 +Node: Accounts screen6735 +Ref: #accounts-screen6865 +Node: Register screen9095 +Ref: #register-screen9252 +Node: Transaction screen11326 +Ref: #transaction-screen11486 +Node: Error screen12356 +Ref: #error-screen12480  End Tag Table diff --git a/doc/other/hledger-ui.1.txt b/doc/other/hledger-ui.1.txt --- a/doc/other/hledger-ui.1.txt +++ b/doc/other/hledger-ui.1.txt @@ -101,14 +101,14 @@ --date2 show, and match with -b/-e/-p/date:, secondary dates instead - -C --cleared - include only cleared postings/txns + -U --unmarked + include only unmarked postings/txns (can combine with -P or -C) - --pending + -P --pending include only pending postings/txns - -U --uncleared - include only uncleared (and pending) postings/txns + -C --cleared + include only cleared postings/txns -R --real include only non-virtual postings @@ -151,45 +151,50 @@ The cursor keys navigate: right (or enter) goes deeper, left returns to the previous screen, up/down/page up/page down/home/end move up and - down through lists. Vi-style h/j/k/l movement keys are also supported. - A tip: movement speed is limited by your keyboard repeat rate, to move - faster you may want to adjust it. (If you're on a mac, the Karabiner - app is one way to do that.) + down through lists. Vi-style (h/j/k/l) and Emacs-style + (CTRL-p/CTRL-n/CTRL-f/CTRL-b) movement keys are also supported. A tip: + movement speed is limited by your keyboard repeat rate, to move faster + you may want to adjust it. (If you're on a mac, the Karabiner app is + one way to do that.) - With shift pressed, the cursor keys adjust the report period, limiting - the transactions to be shown (by default, all are shown). - shift-down/up steps downward and upward through these standard report + With shift pressed, the cursor keys adjust the report period, limiting + the transactions to be shown (by default, all are shown). + shift-down/up steps downward and upward through these standard report period durations: year, quarter, month, week, day. Then, - shift-left/right moves to the previous/next period. t sets the report - period to today. With the --watch option, when viewing a "current" - period (the current day, week, month, quarter, or year), the period - will move automatically to track the current date. To set a non-stan- + shift-left/right moves to the previous/next period. t sets the report + period to today. With the --watch option, when viewing a "current" + period (the current day, week, month, quarter, or year), the period + will move automatically to track the current date. To set a non-stan- dard period, you can use / and a date: query. - / lets you set a general filter query limiting the data shown, using - the same query terms as in hledger and hledger-web. While editing the - query, you can use CTRL-a/e/d/k, BS, cursor keys; press ENTER to set + / lets you set a general filter query limiting the data shown, using + the same query terms as in hledger and hledger-web. While editing the + query, you can use CTRL-a/e/d/k, BS, cursor keys; press ENTER to set it, or ESCAPEto cancel. There are also keys for quickly adjusting some - common filters like account depth and cleared/uncleared (see below). + common filters like account depth and transaction status (see below). BACKSPACE or DELETE removes all filters, showing all transactions. - ESCAPE removes all filters and jumps back to the top screen. Or, it + ESCAPE removes all filters and jumps back to the top screen. Or, it cancels a minibuffer edit or help dialog in progress. - g reloads from the data file(s) and updates the current screen and any - previous screens. (With large files, this could cause a noticeable + CTRL-l redraws the screen and centers the selection if possible (selec- + tions near the top won't be centered, since we don't scroll above the + top). + + g reloads from the data file(s) and updates the current screen and any + previous screens. (With large files, this could cause a noticeable pause.) - I toggles balance assertion checking. Disabling balance assertions + I toggles balance assertion checking. Disabling balance assertions temporarily can be useful for troubleshooting. - a runs command-line hledger's add command, and reloads the updated + a runs command-line hledger's add command, and reloads the updated file. This allows some basic data entry. - E runs $HLEDGER_UI_EDITOR, or $EDITOR, or a default (emac- + E runs $HLEDGER_UI_EDITOR, or $EDITOR, or a default (emac- sclient -a "" -nw) on the journal file. With some editors (emacs, vi), - the cursor will be positioned at the current transaction when invoked - from the register and transaction screens, and at the error location + the cursor will be positioned at the current transaction when invoked + from the register and transaction screens, and at the error location (if possible) when invoked from the error screen. q quits the application. @@ -198,42 +203,44 @@ SCREENS Accounts screen - This is normally the first screen displayed. It lists accounts and - their balances, like hledger's balance command. By default, it shows - all accounts and their latest ending balances (including the balances - of subaccounts). if you specify a query on the command line, it shows + This is normally the first screen displayed. It lists accounts and + their balances, like hledger's balance command. By default, it shows + all accounts and their latest ending balances (including the balances + of subaccounts). if you specify a query on the command line, it shows just the matched accounts and the balances from matched transactions. - Account names are normally indented to show the hierarchy (tree mode). + Account names are normally indented to show the hierarchy (tree mode). To see less detail, set a depth limit by pressing a number key, 1 to 9. 0 shows even less detail, collapsing all accounts to a single total. - - and + (or =) decrease and increase the depth limit. To remove the - depth limit, set it higher than the maximum account depth, or press + and + (or =) decrease and increase the depth limit. To remove the + depth limit, set it higher than the maximum account depth, or press ESCAPE. - F toggles flat mode, in which accounts are shown as a flat list, with - their full names. In this mode, account balances exclude subaccounts, - except for accounts at the depth limit (as with hledger's balance com- + F toggles flat mode, in which accounts are shown as a flat list, with + their full names. In this mode, account balances exclude subaccounts, + except for accounts at the depth limit (as with hledger's balance com- mand). H toggles between showing historical balances or period balances. His- - torical balances (the default) are ending balances at the end of the - report period, taking into account all transactions before that date - (filtered by the filter query if any), including transactions before - the start of the report period. In other words, historical balances - are what you would see on a bank statement for that account (unless - disturbed by a filter query). Period balances ignore transactions + torical balances (the default) are ending balances at the end of the + report period, taking into account all transactions before that date + (filtered by the filter query if any), including transactions before + the start of the report period. In other words, historical balances + are what you would see on a bank statement for that account (unless + disturbed by a filter query). Period balances ignore transactions before the report start date, so they show the change in balance during the report period. They are more useful eg when viewing a time log. - C toggles cleared mode, in which uncleared transactions and postings - are not shown. U toggles uncleared mode, in which only uncleared - transactions/postings are shown. + U toggles filtering by unmarked status, including or excluding unmarked + postings in the balances. Similarly, P toggles pending postings, and C + toggles cleared postings. (By default, balances include all postings; + if you activate one or two status filters, only those postings are + included; and if you activate all three, the filter is removed.) R toggles real mode, in which virtual postings are ignored. - Z toggles nonzero mode, in which only accounts with nonzero balances - are shown (hledger-ui shows zero items by default, unlike command-line + Z toggles nonzero mode, in which only accounts with nonzero balances + are shown (hledger-ui shows zero items by default, unlike command-line hledger). Press right or enter to view an account's transactions register. @@ -242,32 +249,35 @@ This screen shows the transactions affecting a particular account, like a check register. Each line represents one transaction and shows: - o the other account(s) involved, in abbreviated form. (If there are - both real and virtual postings, it shows only the accounts affected + o the other account(s) involved, in abbreviated form. (If there are + both real and virtual postings, it shows only the accounts affected by real postings.) - o the overall change to the current account's balance; positive for an + o the overall change to the current account's balance; positive for an inflow to this account, negative for an outflow. o the running historical total or period total for the current account, - after the transaction. This can be toggled with H. Similar to the - accounts screen, the historical total is affected by transactions - (filtered by the filter query) before the report start date, while + after the transaction. This can be toggled with H. Similar to the + accounts screen, the historical total is affected by transactions + (filtered by the filter query) before the report start date, while the period total is not. If the historical total is not disturbed by - a filter query, it will be the running historical balance you would + a filter query, it will be the running historical balance you would see on a bank register for the current account. - If the accounts screen was in tree mode, the register screen will + If the accounts screen was in tree mode, the register screen will include transactions from both the current account and its subaccounts. - If the accounts screen was in flat mode, and a non-depth-clipped - account was selected, the register screen will exclude transactions + If the accounts screen was in flat mode, and a non-depth-clipped + account was selected, the register screen will exclude transactions from subaccounts. In other words, the register always shows the trans- - actions responsible for the period balance shown on the accounts + actions responsible for the period balance shown on the accounts screen. As on the accounts screen, this can be toggled with F. - C toggles cleared mode, in which uncleared transactions and postings - are not shown. U toggles uncleared mode, in which only uncleared - transactions/postings are shown. + U toggles filtering by unmarked status, showing or hiding unmarked + transactions. Similarly, P toggles pending transactions, and C toggles + cleared transactions. (By default, transactions with all statuses are + shown; if you activate one or two status filters, only those transac- + tions are shown; and if you activate all three, the filter is + removed.)q R toggles real mode, in which virtual postings are ignored. @@ -359,4 +369,4 @@ -hledger-ui 1.2 March 2017 hledger-ui(1) +hledger-ui 1.3 June 2017 hledger-ui(1) diff --git a/doc/other/hledger-web.1 b/doc/other/hledger-web.1 --- a/doc/other/hledger-web.1 +++ b/doc/other/hledger-web.1 @@ -1,5 +1,5 @@ -.TH "hledger\-web" "1" "March 2017" "hledger\-web 1.2" "hledger User Manuals" +.TH "hledger\-web" "1" "June 2017" "hledger\-web 1.3" "hledger User Manuals" @@ -202,18 +202,18 @@ .RS .RE .TP -.B \f[C]\-C\ \-\-cleared\f[] -include only cleared postings/txns +.B \f[C]\-U\ \-\-unmarked\f[] +include only unmarked postings/txns (can combine with \-P or \-C) .RS .RE .TP -.B \f[C]\-\-pending\f[] +.B \f[C]\-P\ \-\-pending\f[] include only pending postings/txns .RS .RE .TP -.B \f[C]\-U\ \-\-uncleared\f[] -include only uncleared (and pending) postings/txns +.B \f[C]\-C\ \-\-cleared\f[] +include only cleared postings/txns .RS .RE .TP diff --git a/doc/other/hledger-web.1.info b/doc/other/hledger-web.1.info --- a/doc/other/hledger-web.1.info +++ b/doc/other/hledger-web.1.info @@ -3,7 +3,7 @@  File: hledger-web.1.info, Node: Top, Next: OPTIONS, Up: (dir) -hledger-web(1) hledger-web 1.2 +hledger-web(1) hledger-web 1.3 ****************************** hledger-web is hledger's web interface. It starts a simple web @@ -149,15 +149,15 @@ '--date2' show, and match with -b/-e/-p/date:, secondary dates instead -'-C --cleared' +'-U --unmarked' - include only cleared postings/txns -'--pending' + include only unmarked postings/txns (can combine with -P or -C) +'-P --pending' include only pending postings/txns -'-U --uncleared' +'-C --cleared' - include only uncleared (and pending) postings/txns + include only cleared postings/txns '-R --real' include only non-virtual postings diff --git a/doc/other/hledger-web.1.txt b/doc/other/hledger-web.1.txt --- a/doc/other/hledger-web.1.txt +++ b/doc/other/hledger-web.1.txt @@ -146,14 +146,14 @@ --date2 show, and match with -b/-e/-p/date:, secondary dates instead - -C --cleared - include only cleared postings/txns + -U --unmarked + include only unmarked postings/txns (can combine with -P or -C) - --pending + -P --pending include only pending postings/txns - -U --uncleared - include only uncleared (and pending) postings/txns + -C --cleared + include only cleared postings/txns -R --real include only non-virtual postings @@ -237,4 +237,4 @@ -hledger-web 1.2 March 2017 hledger-web(1) +hledger-web 1.3 June 2017 hledger-web(1) diff --git a/doc/other/hledger_csv.5 b/doc/other/hledger_csv.5 --- a/doc/other/hledger_csv.5 +++ b/doc/other/hledger_csv.5 @@ -1,5 +1,5 @@ -.TH "hledger_csv" "5" "March 2017" "hledger 1.2" "hledger User Manuals" +.TH "hledger_csv" "5" "June 2017" "hledger 1.3" "hledger User Manuals" @@ -18,7 +18,7 @@ you\[aq]ll need to adjust. At minimum, the rules file must specify the \f[C]date\f[] and \f[C]amount\f[] fields. -For an example, see How to read CSV files. +For an example, see Cookbook: convert CSV files. .PP To learn about \f[I]exporting\f[] CSV, see CSV output. .SH CSV RULES @@ -90,7 +90,7 @@ \f[C]date\f[], \f[C]date2\f[], \f[C]status\f[], \f[C]code\f[], \f[C]description\f[], \f[C]comment\f[], \f[C]account1\f[], \f[C]account2\f[], \f[C]amount\f[], \f[C]amount\-in\f[], -\f[C]amount\-out\f[], \f[C]currency\f[]. +\f[C]amount\-out\f[], \f[C]currency\f[], \f[C]balance\f[]. Eg: .IP .nf @@ -195,7 +195,7 @@ include\ common.rules \f[] .fi -.SH TIPS +.SH CSV TIPS .PP Each generated journal entry will have two postings, to \f[C]account1\f[] and \f[C]account2\f[] respectively. @@ -210,6 +210,11 @@ \f[C]currency\f[] pseudo field which will be automatically prepended to the amount. (Or you can do the same thing with a field assignment.) +.PP +If the CSV includes a running balance, you can assign that to the +\f[C]balance\f[] pseudo field to generate a balance assertion on +\f[C]account1\f[] whenever the balance field is non\-empty. +(Eg to double\-check your bank\[aq]s balance calculation.) .PP If an amount value is parenthesised, it will be de\-parenthesised and sign\-flipped automatically. diff --git a/doc/other/hledger_csv.5.info b/doc/other/hledger_csv.5.info --- a/doc/other/hledger_csv.5.info +++ b/doc/other/hledger_csv.5.info @@ -3,7 +3,7 @@  File: hledger_csv.5.info, Node: Top, Next: CSV RULES, Up: (dir) -hledger_csv(5) hledger 1.2 +hledger_csv(5) hledger 1.3 ************************** hledger can read CSV files, converting each CSV record into a journal @@ -13,16 +13,16 @@ with '--rules-file PATH'. hledger will create it if necessary, with some default rules which you'll need to adjust. At minimum, the rules file must specify the 'date' and 'amount' fields. For an example, see -How to read CSV files. +Cookbook: convert CSV files. To learn about _exporting_ CSV, see CSV output. * Menu: * CSV RULES:: -* TIPS:: +* CSV TIPS::  -File: hledger_csv.5.info, Node: CSV RULES, Next: TIPS, Prev: Top, Up: Top +File: hledger_csv.5.info, Node: CSV RULES, Next: CSV TIPS, Prev: Top, Up: Top 1 CSV RULES *********** @@ -89,7 +89,8 @@ whitespace; uninteresting names may be left blank), and (b) assigns them to journal entry fields if you use any of these standard field names: 'date', 'date2', 'status', 'code', 'description', 'comment', 'account1', -'account2', 'amount', 'amount-in', 'amount-out', 'currency'. Eg: +'account2', 'amount', 'amount-in', 'amount-out', 'currency', 'balance'. +Eg: # use the 1st, 2nd and 4th CSV fields as the entry's date, description and amount, # and give the 7th and 8th fields meaningful names for later reference: @@ -170,10 +171,10 @@ include common.rules  -File: hledger_csv.5.info, Node: TIPS, Prev: CSV RULES, Up: Top +File: hledger_csv.5.info, Node: CSV TIPS, Prev: CSV RULES, Up: Top -2 TIPS -****** +2 CSV TIPS +********** Each generated journal entry will have two postings, to 'account1' and 'account2' respectively. Currently it's not possible to generate @@ -186,6 +187,11 @@ 'currency' pseudo field which will be automatically prepended to the amount. (Or you can do the same thing with a field assignment.) + If the CSV includes a running balance, you can assign that to the +'balance' pseudo field to generate a balance assertion on 'account1' +whenever the balance field is non-empty. (Eg to double-check your +bank's balance calculation.) + If an amount value is parenthesised, it will be de-parenthesised and sign-flipped automatically. @@ -195,21 +201,21 @@  Tag Table: Node: Top74 -Node: CSV RULES800 -Ref: #csv-rules906 -Node: skip1149 -Ref: #skip1245 -Node: date-format1417 -Ref: #date-format1546 -Node: field list2052 -Ref: #field-list2191 -Node: field assignment2886 -Ref: #field-assignment3043 -Node: conditional block3547 -Ref: #conditional-block3703 -Node: include4599 -Ref: #include4710 -Node: TIPS4941 -Ref: #tips5025 +Node: CSV RULES810 +Ref: #csv-rules920 +Node: skip1163 +Ref: #skip1259 +Node: date-format1431 +Ref: #date-format1560 +Node: field list2066 +Ref: #field-list2205 +Node: field assignment2910 +Ref: #field-assignment3067 +Node: conditional block3571 +Ref: #conditional-block3727 +Node: include4623 +Ref: #include4734 +Node: CSV TIPS4965 +Ref: #csv-tips5061  End Tag Table diff --git a/doc/other/hledger_csv.5.txt b/doc/other/hledger_csv.5.txt --- a/doc/other/hledger_csv.5.txt +++ b/doc/other/hledger_csv.5.txt @@ -13,8 +13,8 @@ .rules suffix (eg: mybank.csv.rules); or, you can specify the file with --rules-file PATH. hledger will create it if necessary, with some default rules which you'll need to adjust. At minimum, the rules file - must specify the date and amount fields. For an example, see How to - read CSV files. + must specify the date and amount fields. For an example, see Cookbook: + convert CSV files. To learn about exporting CSV, see CSV output. @@ -58,7 +58,7 @@ space; uninteresting names may be left blank), and (b) assigns them to journal entry fields if you use any of these standard field names: date, date2, status, code, description, comment, account1, account2, - amount, amount-in, amount-out, currency. Eg: + amount, amount-in, amount-out, currency, balance. Eg: # use the 1st, 2nd and 4th CSV fields as the entry's date, description and amount, # and give the 7th and 8th fields meaningful names for later reference: @@ -123,7 +123,7 @@ # rules reused with several CSV files include common.rules -TIPS +CSV TIPS Each generated journal entry will have two postings, to account1 and account2 respectively. Currently it's not possible to generate entries with more than two postings. @@ -135,16 +135,21 @@ currency pseudo field which will be automatically prepended to the amount. (Or you can do the same thing with a field assignment.) - If an amount value is parenthesised, it will be de-parenthesised and + If the CSV includes a running balance, you can assign that to the bal- + ance pseudo field to generate a balance assertion on account1 whenever + the balance field is non-empty. (Eg to double-check your bank's bal- + ance calculation.) + + If an amount value is parenthesised, it will be de-parenthesised and sign-flipped automatically. - The generated journal entries will be sorted by date. The original + The generated journal entries will be sorted by date. The original order of same-day entries will be preserved, usually. 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) @@ -158,7 +163,7 @@ 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) @@ -166,4 +171,4 @@ -hledger 1.2 March 2017 hledger_csv(5) +hledger 1.3 June 2017 hledger_csv(5) diff --git a/doc/other/hledger_journal.5 b/doc/other/hledger_journal.5 --- a/doc/other/hledger_journal.5 +++ b/doc/other/hledger_journal.5 @@ -1,6 +1,6 @@ .\"t -.TH "hledger_journal" "5" "March 2017" "hledger 1.2" "hledger User Manuals" +.TH "hledger_journal" "5" "June 2017" "hledger 1.3" "hledger User Manuals" @@ -61,34 +61,49 @@ .SH FILE FORMAT .SS Transactions .PP -Transactions are represented by journal entries. -Each begins with a simple date in column 0, followed by three optional -fields with spaces between them: +Transactions are movements of some quantity of commodities between named +accounts. +Each transaction is represented by a journal entry beginning with a +simple date in column 0. +This can be followed by any of the following, separated by spaces: .IP \[bu] 2 -a status flag, which can be empty or \f[C]!\f[] or \f[C]*\f[] (meaning -"uncleared", "pending" and "cleared", or whatever you want) +(optional) a status character (empty, \f[C]!\f[], or \f[C]*\f[]) .IP \[bu] 2 -a transaction code (eg a check number), +(optional) a transaction code (any short number or text, enclosed in +parentheses) .IP \[bu] 2 -and/or a description +(optional) a transaction description (any remaining text until end of +line) .PP -then some number of postings, of some amount to some account. -Each posting is on its own line, consisting of: -.IP \[bu] 2 -indentation of one or more spaces (or tabs) +Then comes zero or more (but usually at least 2) indented lines +representing... +.SS Postings +.PP +A posting is an addition of some amount to, or removal of some amount +from, an account. +Each posting line begins with at least one space or tab (2 or 4 spaces +is common), followed by: .IP \[bu] 2 -optionally, a \f[C]!\f[] or \f[C]*\f[] status flag followed by a space +(optional) a status character (empty, \f[C]!\f[], or \f[C]*\f[]), +followed by a space .IP \[bu] 2 -an account name, optionally containing single spaces +(required) an account name (any text, optionally containing \f[B]single +spaces\f[], until end of line or a double space) .IP \[bu] 2 -optionally, two or more spaces or tabs followed by an amount +(optional) \f[B]two or more spaces\f[] or tabs followed by an amount. .PP -Usually there are two or more postings, though one or none is also -possible. -The posting amounts within a transaction must always balance, ie add up -to 0. -Optionally one amount can be left blank, in which case it will be -inferred. +Positive amounts are being added to the account, negative amounts are +being removed. +.PP +The amounts within a transaction must always sum up to zero. +As a convenience, one amount may be left blank; it will be inferred so +as to balance the transaction. +.PP +Be sure to note the unusual two\-space delimiter between account name +and amount. +This makes it easy to write account names containing spaces. +But if you accidentally leave only one space (or tab) before the amount, +the amount will be considered part of the account name. .SS Dates .SS Simple dates .PP @@ -195,6 +210,92 @@ \f[C]0123456789/\-.=\f[] characters in this way. With this syntax, DATE infers its year from the transaction and DATE2 infers its year from DATE. +.SS Status +.PP +Transactions, or individual postings within a transaction, can have a +status mark, which is a single character before the transaction +description or posting account name, separated from it by a space, +indicating one of three statuses: +.PP +.TS +tab(@); +l l. +T{ +mark \ +T}@T{ +status +T} +_ +T{ +\ +T}@T{ +unmarked +T} +T{ +\f[C]!\f[] +T}@T{ +pending +T} +T{ +\f[C]*\f[] +T}@T{ +cleared +T} +.TE +.PP +When reporting, you can filter by status with the +\f[C]\-U/\-\-unmarked\f[], \f[C]\-P/\-\-pending\f[], and +\f[C]\-C/\-\-cleared\f[] flags; or the \f[C]status:\f[], +\f[C]status:!\f[], and \f[C]status:*\f[] queries; or the U, P, C keys in +hledger\-ui. +.PP +Note, in Ledger and in older versions of hledger, the "unmarked" state +is called "uncleared". +As of hledger 1.3 we have renamed it to unmarked for clarity. +.PP +To replicate Ledger and old hledger\[aq]s behaviour of also matching +pending, combine \-U and \-P. +.PP +Status marks are optional, but can be helpful eg for reconciling with +real\-world accounts. +Some editor modes provide highlighting and shortcuts for working with +status. +Eg in Emacs ledger\-mode, you can toggle transaction status with C\-c +C\-e, or posting status with C\-c C\-c. +.PP +What "uncleared", "pending", and "cleared" actually mean is up to you. +Here\[aq]s one suggestion: +.PP +.TS +tab(@); +lw(10.5n) lw(59.5n). +T{ +status +T}@T{ +meaning +T} +_ +T{ +uncleared +T}@T{ +recorded but not yet reconciled; needs review +T} +T{ +pending +T}@T{ +tentatively reconciled (if needed, eg during a big reconciliation) +T} +T{ +cleared +T}@T{ +complete, reconciled as far as possible, and considered correct +T} +.TE +.PP +With this scheme, you would use \f[C]\-PC\f[] to see the current balance +at your bank, \f[C]\-U\f[] to see things which will probably hit your +bank soon (like uncashed checks), and no flags to see the most +up\-to\-date state of your finances. .SS Account names .PP Account names typically have several parts separated by a full colon, @@ -470,78 +571,101 @@ .SS Prices .SS Transaction prices .PP -Within a transaction posting, you can record an amount\[aq]s price in -another commodity. -This can be used to document the cost (for a purchase), or selling price -(for a sale), or the exchange rate that was used, for this transaction. -These transaction prices are fixed, and do not change over time. +Within a transaction, you can note an amount\[aq]s price in another +commodity. +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. .PP -Amounts with transaction prices can be displayed in the transaction -price\[aq]s commodity, by using the \f[C]\-\-cost/\-B\f[] flag supported -by most hledger commands (mnemonic: "cost Basis"). +Transaction prices are fixed, and do not change over time. +(Ledger users: Ledger uses a different syntax for fixed prices, +\f[C]{=UNITPRICE}\f[], which hledger currently ignores). .PP There are several ways to record a transaction price: .IP "1." 3 -Write the unit price (aka exchange rate), as \f[C]\@\ UNITPRICE\f[] -after the amount: +Write the price per unit, as \f[C]\@\ UNITPRICE\f[] after the amount: .RS 4 .IP .nf \f[C] 2009/1/1 -\ \ assets:foreign\ currency\ \ \ €100\ \@\ $1.35\ \ ;\ one\ hundred\ euros\ at\ $1.35\ each -\ \ assets:cash +\ \ assets:euros\ \ \ \ \ €100\ \@\ $1.35\ \ ;\ one\ hundred\ euros\ purchased\ at\ $1.35\ each +\ \ assets:dollars\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ;\ balancing\ amount\ is\ \-$135.00 \f[] .fi .RE .IP "2." 3 -Or write the total price, as \f[C]\@\@\ TOTALPRICE\f[] after the amount: +Write the total price, as \f[C]\@\@\ TOTALPRICE\f[] after the amount: .RS 4 .IP .nf \f[C] 2009/1/1 -\ \ assets:foreign\ currency\ \ \ €100\ \@\@\ $135\ \ ;\ one\ hundred\ euros\ at\ $135\ for\ the\ lot -\ \ assets:cash +\ \ assets:euros\ \ \ \ \ €100\ \@\@\ $135\ \ ;\ one\ hundred\ euros\ purchased\ at\ $135\ for\ the\ lot +\ \ assets:dollars \f[] .fi .RE .IP "3." 3 -Or let hledger infer the price so as to balance the transaction. -To permit this, you must fully specify all posting amounts, and their -sum must have a non\-zero amount in exactly two commodities: +Specify amounts for all postings, using exactly two commodities, and let +hledger infer the price that balances the transaction: .RS 4 .IP .nf \f[C] 2009/1/1 -\ \ assets:foreign\ currency\ \ \ €100\ \ \ \ \ \ \ \ \ \ ;\ one\ hundred\ euros -\ \ assets:cash\ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-135\ \ \ \ \ \ \ \ \ \ ;\ exchanged\ for\ $135 +\ \ assets:euros\ \ \ \ \ €100\ \ \ \ \ \ \ \ \ \ ;\ one\ hundred\ euros\ purchased +\ \ assets:dollars\ \ $\-135\ \ \ \ \ \ \ \ \ \ ;\ for\ $135 \f[] .fi .RE .PP -With any of the above examples we get: +Amounts with transaction prices can be displayed in the transaction +price\[aq]s commodity by using the \f[C]\-B/\-\-cost\f[] flag (except +for #551) ("B" is from "cost Basis"). +Eg for the above, here is how \-B affects the balance report: .IP .nf \f[C] -$\ hledger\ print\ \-B -2009/01/01 -\ \ \ \ assets:foreign\ currency\ \ \ \ \ \ \ $135.00 -\ \ \ \ assets:cash\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-135.00 +$\ hledger\ bal\ \-N\ \-\-flat +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-135\ \ assets:dollars +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ €100\ \ assets:euros +$\ hledger\ bal\ \-N\ \-\-flat\ \-B +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-135\ \ assets:dollars +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $135\ \ assets:euros\ \ \ \ #\ <\-\ the\ euros\[aq]\ cost \f[] .fi .PP -Example use for transaction prices: recording the effective conversion -rate of purchases made in a foreign currency. +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\[aq]s postings are reversed, while the transaction is +equivalent, \-B shows something different: +.IP +.nf +\f[C] +2009/1/1 +\ \ assets:dollars\ \ $\-135\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ;\ 135\ dollars\ sold +\ \ assets:euros\ \ \ \ \ €100\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ;\ for\ 100\ euros +\f[] +.fi +.IP +.nf +\f[C] +$\ hledger\ bal\ \-N\ \-\-flat\ \-B +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ €\-100\ \ assets:dollars\ \ #\ <\-\ the\ dollars\[aq]\ selling\ price +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ €100\ \ assets:euros +\f[] +.fi .SS Market prices .PP Market prices are not tied to a particular transaction; they represent historical exchange rates between two commodities. (Ledger calls them historical prices.) For example, the prices published by a stock exchange or the foreign exchange market. -Some commands (balance, currently) can use this information to show the -market value of things at a given date. +hledger can use these prices to show the market value of things at a +given date, see market value. .PP To record market prices, use P directives in the main journal or in an included file. @@ -739,8 +863,7 @@ .SS Regex aliases .PP There is also a more powerful variant that uses a regular expression, -indicated by the forward slashes. -(This was the default behaviour in hledger 0.24\-0.25): +indicated by the forward slashes: .IP .nf \f[C] diff --git a/doc/other/hledger_journal.5.info b/doc/other/hledger_journal.5.info --- a/doc/other/hledger_journal.5.info +++ b/doc/other/hledger_journal.5.info @@ -4,7 +4,7 @@  File: hledger_journal.5.info, Node: Top, Next: FILE FORMAT, Up: (dir) -hledger_journal(5) hledger 1.2 +hledger_journal(5) hledger 1.3 ****************************** hledger's usual data source is a plain text file containing journal @@ -64,7 +64,9 @@ * Menu: * Transactions:: +* Postings:: * Dates:: +* Status:: * Account names:: * Amounts:: * Virtual Postings:: @@ -76,37 +78,57 @@ * Directives::  -File: hledger_journal.5.info, Node: Transactions, Next: Dates, Up: FILE FORMAT +File: hledger_journal.5.info, Node: Transactions, Next: Postings, Up: FILE FORMAT 1.1 Transactions ================ -Transactions are represented by journal entries. Each begins with a -simple date in column 0, followed by three optional fields with spaces -between them: +Transactions are movements of some quantity of commodities between named +accounts. Each transaction is represented by a journal entry beginning +with a simple date in column 0. This can be followed by any of the +following, separated by spaces: - * a status flag, which can be empty or '!' or '*' (meaning - "uncleared", "pending" and "cleared", or whatever you want) - * a transaction code (eg a check number), - * and/or a description + * (optional) a status character (empty, '!', or '*') + * (optional) a transaction code (any short number or text, enclosed + in parentheses) + * (optional) a transaction description (any remaining text until end + of line) - then some number of postings, of some amount to some account. Each -posting is on its own line, consisting of: + Then comes zero or more (but usually at least 2) indented lines +representing... - * indentation of one or more spaces (or tabs) - * optionally, a '!' or '*' status flag followed by a space - * an account name, optionally containing single spaces - * optionally, two or more spaces or tabs followed by an amount + +File: hledger_journal.5.info, Node: Postings, Next: Dates, Prev: Transactions, Up: FILE FORMAT - Usually there are two or more postings, though one or none is also -possible. The posting amounts within a transaction must always balance, -ie add up to 0. Optionally one amount can be left blank, in which case -it will be inferred. +1.2 Postings +============ +A posting is an addition of some amount to, or removal of some amount +from, an account. Each posting line begins with at least one space or +tab (2 or 4 spaces is common), followed by: + + * (optional) a status character (empty, '!', or '*'), followed by a + space + * (required) an account name (any text, optionally containing *single + spaces*, until end of line or a double space) + * (optional) *two or more spaces* or tabs followed by an amount. + + Positive amounts are being added to the account, negative amounts are +being removed. + + The amounts within a transaction must always sum up to zero. As a +convenience, one amount may be left blank; it will be inferred so as to +balance the transaction. + + Be sure to note the unusual two-space delimiter between account name +and amount. This makes it easy to write account names containing +spaces. But if you accidentally leave only one space (or tab) before +the amount, the amount will be considered part of the account name. +  -File: hledger_journal.5.info, Node: Dates, Next: Account names, Prev: Transactions, Up: FILE FORMAT +File: hledger_journal.5.info, Node: Dates, Next: Status, Prev: Postings, Up: FILE FORMAT -1.2 Dates +1.3 Dates ========= * Menu: @@ -118,7 +140,7 @@  File: hledger_journal.5.info, Node: Simple dates, Next: Secondary dates, Up: Dates -1.2.1 Simple dates +1.3.1 Simple dates ------------------ Within a journal file, transaction dates use Y/M/D (or Y-M-D or Y.M.D) @@ -131,7 +153,7 @@  File: hledger_journal.5.info, Node: Secondary dates, Next: Posting dates, Prev: Simple dates, Up: Dates -1.2.2 Secondary dates +1.3.2 Secondary dates --------------------- Real-life transactions sometimes involve more than one date - eg the @@ -172,7 +194,7 @@  File: hledger_journal.5.info, Node: Posting dates, Prev: Secondary dates, Up: Dates -1.2.3 Posting dates +1.3.3 Posting dates ------------------- You can give individual postings a different date from their parent @@ -205,9 +227,59 @@ transaction and DATE2 infers its year from DATE.  -File: hledger_journal.5.info, Node: Account names, Next: Amounts, Prev: Dates, Up: FILE FORMAT +File: hledger_journal.5.info, Node: Status, Next: Account names, Prev: Dates, Up: FILE FORMAT -1.3 Account names +1.4 Status +========== + +Transactions, or individual postings within a transaction, can have a +status mark, which is a single character before the transaction +description or posting account name, separated from it by a space, +indicating one of three statuses: + +mark status + +----------------- + unmarked +'!' pending +'*' cleared + + When reporting, you can filter by status with the '-U/--unmarked', +'-P/--pending', and '-C/--cleared' flags; or the 'status:', 'status:!', +and 'status:*' queries; or the U, P, C keys in hledger-ui. + + Note, in Ledger and in older versions of hledger, the "unmarked" +state is called "uncleared". As of hledger 1.3 we have renamed it to +unmarked for clarity. + + To replicate Ledger and old hledger's behaviour of also matching +pending, combine -U and -P. + + Status marks are optional, but can be helpful eg for reconciling with +real-world accounts. Some editor modes provide highlighting and +shortcuts for working with status. Eg in Emacs ledger-mode, you can +toggle transaction status with C-c C-e, or posting status with C-c C-c. + + What "uncleared", "pending", and "cleared" actually mean is up to +you. Here's one suggestion: + +status meaning +-------------------------------------------------------------------------- +uncleared recorded but not yet reconciled; needs review +pending tentatively reconciled (if needed, eg during a big + reconciliation) +cleared complete, reconciled as far as possible, and considered + correct + + With this scheme, you would use '-PC' to see the current balance at +your bank, '-U' to see things which will probably hit your bank soon +(like uncashed checks), and no flags to see the most up-to-date state of +your finances. + + +File: hledger_journal.5.info, Node: Account names, Next: Amounts, Prev: Status, Up: FILE FORMAT + +1.5 Account names ================= Account names typically have several parts separated by a full colon, @@ -225,7 +297,7 @@  File: hledger_journal.5.info, Node: Amounts, Next: Virtual Postings, Prev: Account names, Up: FILE FORMAT -1.4 Amounts +1.6 Amounts =========== After the account name, there is usually an amount. Important: between @@ -280,7 +352,7 @@  File: hledger_journal.5.info, Node: Virtual Postings, Next: Balance Assertions, Prev: Amounts, Up: FILE FORMAT -1.5 Virtual Postings +1.7 Virtual Postings ==================== When you parenthesise the account name in a posting, we call that a @@ -315,7 +387,7 @@  File: hledger_journal.5.info, Node: Balance Assertions, Next: Balance Assignments, Prev: Virtual Postings, Up: FILE FORMAT -1.6 Balance Assertions +1.8 Balance Assertions ====================== hledger supports Ledger-style balance assertions in journal files. @@ -349,7 +421,7 @@  File: hledger_journal.5.info, Node: Assertions and ordering, Next: Assertions and included files, Up: Balance Assertions -1.6.1 Assertions and ordering +1.8.1 Assertions and ordering ----------------------------- hledger sorts an account's postings and assertions first by date and @@ -368,7 +440,7 @@  File: hledger_journal.5.info, Node: Assertions and included files, Next: Assertions and multiple -f options, Prev: Assertions and ordering, Up: Balance Assertions -1.6.2 Assertions and included files +1.8.2 Assertions and included files ----------------------------------- With included files, things are a little more complicated. Including @@ -380,7 +452,7 @@  File: hledger_journal.5.info, Node: Assertions and multiple -f options, Next: Assertions and commodities, Prev: Assertions and included files, Up: Balance Assertions -1.6.3 Assertions and multiple -f options +1.8.3 Assertions and multiple -f options ---------------------------------------- Balance assertions don't work well across files specified with multiple @@ -389,7 +461,7 @@  File: hledger_journal.5.info, Node: Assertions and commodities, Next: Assertions and subaccounts, Prev: Assertions and multiple -f options, Up: Balance Assertions -1.6.4 Assertions and commodities +1.8.4 Assertions and commodities -------------------------------- The asserted balance must be a simple single-commodity amount, and in @@ -408,7 +480,7 @@  File: hledger_journal.5.info, Node: Assertions and subaccounts, Next: Assertions and virtual postings, Prev: Assertions and commodities, Up: Balance Assertions -1.6.5 Assertions and subaccounts +1.8.5 Assertions and subaccounts -------------------------------- Balance assertions do not count the balance from subaccounts; they check @@ -431,7 +503,7 @@  File: hledger_journal.5.info, Node: Assertions and virtual postings, Prev: Assertions and subaccounts, Up: Balance Assertions -1.6.6 Assertions and virtual postings +1.8.6 Assertions and virtual postings ------------------------------------- Balance assertions are checked against all postings, both real and @@ -441,7 +513,7 @@  File: hledger_journal.5.info, Node: Balance Assignments, Next: Prices, Prev: Balance Assertions, Up: FILE FORMAT -1.7 Balance Assignments +1.9 Balance Assignments ======================= Ledger-style balance assignments are also supported. These are like @@ -474,8 +546,8 @@  File: hledger_journal.5.info, Node: Prices, Next: Comments, Prev: Balance Assignments, Up: FILE FORMAT -1.8 Prices -========== +1.10 Prices +=========== * Menu: @@ -485,64 +557,75 @@  File: hledger_journal.5.info, Node: Transaction prices, Next: Market prices, Up: Prices -1.8.1 Transaction prices ------------------------- +1.10.1 Transaction prices +------------------------- -Within a transaction posting, you can record an amount's price in -another commodity. This can be used to document the cost (for a -purchase), or selling price (for a sale), or the exchange rate that was -used, for this transaction. These transaction prices are fixed, and do -not change over time. +Within a transaction, you can note an amount's price in another +commodity. 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. - Amounts with transaction prices can be displayed in the transaction -price's commodity, by using the '--cost/-B' flag supported by most -hledger commands (mnemonic: "cost Basis"). + Transaction prices are fixed, and do not change over time. (Ledger +users: Ledger uses a different syntax for fixed prices, '{=UNITPRICE}', +which hledger currently ignores). There are several ways to record a transaction price: - 1. Write the unit price (aka exchange rate), as '@ UNITPRICE' after - the amount: + 1. Write the price per unit, as '@ UNITPRICE' after the amount: 2009/1/1 - assets:foreign currency €100 @ $1.35 ; one hundred euros at $1.35 each - assets:cash + assets:euros €100 @ $1.35 ; one hundred euros purchased at $1.35 each + assets:dollars ; balancing amount is -$135.00 - 2. Or write the total price, as '@@ TOTALPRICE' after the amount: + 2. Write the total price, as '@@ TOTALPRICE' after the amount: 2009/1/1 - assets:foreign currency €100 @@ $135 ; one hundred euros at $135 for the lot - assets:cash + assets:euros €100 @@ $135 ; one hundred euros purchased at $135 for the lot + assets:dollars - 3. Or let hledger infer the price so as to balance the transaction. - To permit this, you must fully specify all posting amounts, and - their sum must have a non-zero amount in exactly two commodities: + 3. Specify amounts for all postings, using exactly two commodities, + and let hledger infer the price that balances the transaction: 2009/1/1 - assets:foreign currency €100 ; one hundred euros - assets:cash $-135 ; exchanged for $135 + assets:euros €100 ; one hundred euros purchased + assets:dollars $-135 ; for $135 - With any of the above examples we get: + Amounts with transaction prices can be displayed in the transaction +price's commodity by using the '-B/--cost' flag (except for #551) ("B" +is from "cost Basis"). Eg for the above, here is how -B affects the +balance report: -$ hledger print -B -2009/01/01 - assets:foreign currency $135.00 - assets:cash $-135.00 +$ hledger bal -N --flat + $-135 assets:dollars + €100 assets:euros +$ hledger bal -N --flat -B + $-135 assets:dollars + $135 assets:euros # <- the euros' cost - Example use for transaction prices: recording the effective -conversion rate of purchases made in a foreign currency. + 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: +2009/1/1 + assets:dollars $-135 ; 135 dollars sold + assets:euros €100 ; for 100 euros + +$ hledger bal -N --flat -B + €-100 assets:dollars # <- the dollars' selling price + €100 assets:euros +  File: hledger_journal.5.info, Node: Market prices, Prev: Transaction prices, Up: Prices -1.8.2 Market prices -------------------- +1.10.2 Market prices +-------------------- Market prices are not tied to a particular transaction; they represent historical exchange rates between two commodities. (Ledger calls them historical prices.) For example, the prices published by a stock -exchange or the foreign exchange market. Some commands (balance, -currently) can use this information to show the market value of things -at a given date. +exchange or the foreign exchange market. hledger can use these prices +to show the market value of things at a given date, see market value. To record market prices, use P directives in the main journal or in an included file. Their format is: @@ -564,8 +647,8 @@  File: hledger_journal.5.info, Node: Comments, Next: Tags, Prev: Prices, Up: FILE FORMAT -1.9 Comments -============ +1.11 Comments +============= Lines in the journal beginning with a semicolon (';') or hash ('#') or asterisk ('*') are comments, and will be ignored. (Asterisk comments @@ -604,7 +687,7 @@  File: hledger_journal.5.info, Node: Tags, Next: Directives, Prev: Comments, Up: FILE FORMAT -1.10 Tags +1.12 Tags ========= Tags are a way to add extra labels or labelled data to postings and @@ -650,7 +733,7 @@  File: hledger_journal.5.info, Node: Implicit tags, Up: Tags -1.10.1 Implicit tags +1.12.1 Implicit tags -------------------- Some predefined "implicit" tags are also provided: @@ -668,7 +751,7 @@  File: hledger_journal.5.info, Node: Directives, Prev: Tags, Up: FILE FORMAT -1.11 Directives +1.13 Directives =============== * Menu: @@ -685,7 +768,7 @@  File: hledger_journal.5.info, Node: Account aliases, Next: account directive, Up: Directives -1.11.1 Account aliases +1.13.1 Account aliases ---------------------- You can define aliases which rewrite your account names (after reading @@ -710,7 +793,7 @@  File: hledger_journal.5.info, Node: Basic aliases, Next: Regex aliases, Up: Account aliases -1.11.1.1 Basic aliases +1.13.1.1 Basic aliases ...................... To set an account alias, use the 'alias' directive in your journal file. @@ -733,12 +816,11 @@  File: hledger_journal.5.info, Node: Regex aliases, Next: Multiple aliases, Prev: Basic aliases, Up: Account aliases -1.11.1.2 Regex aliases +1.13.1.2 Regex aliases ...................... There is also a more powerful variant that uses a regular expression, -indicated by the forward slashes. (This was the default behaviour in -hledger 0.24-0.25): +indicated by the forward slashes: alias /REGEX/ = REPLACEMENT @@ -757,7 +839,7 @@  File: hledger_journal.5.info, Node: Multiple aliases, Next: end aliases, Prev: Regex aliases, Up: Account aliases -1.11.1.3 Multiple aliases +1.13.1.3 Multiple aliases ......................... You can define as many aliases as you like using directives or @@ -773,7 +855,7 @@  File: hledger_journal.5.info, Node: end aliases, Prev: Multiple aliases, Up: Account aliases -1.11.1.4 end aliases +1.13.1.4 end aliases .................... You can clear (forget) all currently defined aliases with the 'end @@ -784,7 +866,7 @@  File: hledger_journal.5.info, Node: account directive, Next: apply account directive, Prev: Account aliases, Up: Directives -1.11.2 account directive +1.13.2 account directive ------------------------ The 'account' directive predefines account names, as in Ledger and @@ -805,7 +887,7 @@  File: hledger_journal.5.info, Node: apply account directive, Next: Multi-line comments, Prev: account directive, Up: Directives -1.11.3 apply account directive +1.13.3 apply account directive ------------------------------ You can specify a parent account which will be prepended to all accounts @@ -841,7 +923,7 @@  File: hledger_journal.5.info, Node: Multi-line comments, Next: commodity directive, Prev: apply account directive, Up: Directives -1.11.4 Multi-line comments +1.13.4 Multi-line comments -------------------------- A line containing just 'comment' starts a multi-line comment, and a line @@ -850,7 +932,7 @@  File: hledger_journal.5.info, Node: commodity directive, Next: Default commodity, Prev: Multi-line comments, Up: Directives -1.11.5 commodity directive +1.13.5 commodity directive -------------------------- The 'commodity' directive predefines commodities (currently this is just @@ -882,7 +964,7 @@  File: hledger_journal.5.info, Node: Default commodity, Next: Default year, Prev: commodity directive, Up: Directives -1.11.6 Default commodity +1.13.6 Default commodity ------------------------ The D directive sets a default commodity (and display format), to be @@ -902,7 +984,7 @@  File: hledger_journal.5.info, Node: Default year, Next: Including other files, Prev: Default commodity, Up: Directives -1.11.7 Default year +1.13.7 Default year ------------------- You can set a default year to be used for subsequent dates which don't @@ -928,7 +1010,7 @@  File: hledger_journal.5.info, Node: Including other files, Prev: Default year, Up: Directives -1.11.8 Including other files +1.13.8 Including other files ---------------------------- You can pull in the content of additional journal files by writing an @@ -967,77 +1049,81 @@ Node: Top78 Node: FILE FORMAT2292 Ref: #file-format2418 -Node: Transactions2601 -Ref: #transactions2721 -Node: Dates3663 -Ref: #dates3791 -Node: Simple dates3856 -Ref: #simple-dates3984 -Node: Secondary dates4350 -Ref: #secondary-dates4506 -Node: Posting dates6069 -Ref: #posting-dates6200 -Node: Account names7574 -Ref: #account-names7713 -Node: Amounts8200 -Ref: #amounts8338 -Node: Virtual Postings10439 -Ref: #virtual-postings10600 -Node: Balance Assertions11820 -Ref: #balance-assertions11997 -Node: Assertions and ordering12893 -Ref: #assertions-and-ordering13081 -Node: Assertions and included files13781 -Ref: #assertions-and-included-files14024 -Node: Assertions and multiple -f options14357 -Ref: #assertions-and-multiple--f-options14613 -Node: Assertions and commodities14745 -Ref: #assertions-and-commodities14982 -Node: Assertions and subaccounts15678 -Ref: #assertions-and-subaccounts15912 -Node: Assertions and virtual postings16433 -Ref: #assertions-and-virtual-postings16642 -Node: Balance Assignments16784 -Ref: #balance-assignments16953 -Node: Prices18072 -Ref: #prices18205 -Node: Transaction prices18256 -Ref: #transaction-prices18401 -Node: Market prices19978 -Ref: #market-prices20113 -Node: Comments21086 -Ref: #comments21208 -Node: Tags22321 -Ref: #tags22441 -Node: Implicit tags23870 -Ref: #implicit-tags23978 -Node: Directives24495 -Ref: #directives24610 -Node: Account aliases24803 -Ref: #account-aliases24949 -Node: Basic aliases25553 -Ref: #basic-aliases25698 -Node: Regex aliases26388 -Ref: #regex-aliases26558 -Node: Multiple aliases27329 -Ref: #multiple-aliases27503 -Node: end aliases28001 -Ref: #end-aliases28143 -Node: account directive28244 -Ref: #account-directive28426 -Node: apply account directive28722 -Ref: #apply-account-directive28920 -Node: Multi-line comments29579 -Ref: #multi-line-comments29771 -Node: commodity directive29899 -Ref: #commodity-directive30085 -Node: Default commodity30957 -Ref: #default-commodity31132 -Node: Default year31669 -Ref: #default-year31836 -Node: Including other files32259 -Ref: #including-other-files32418 -Node: EDITOR SUPPORT32815 -Ref: #editor-support32935 +Node: Transactions2625 +Ref: #transactions2748 +Node: Postings3313 +Ref: #postings3442 +Node: Dates4437 +Ref: #dates4554 +Node: Simple dates4619 +Ref: #simple-dates4747 +Node: Secondary dates5113 +Ref: #secondary-dates5269 +Node: Posting dates6832 +Ref: #posting-dates6963 +Node: Status8337 +Ref: #status8461 +Node: Account names10175 +Ref: #account-names10315 +Node: Amounts10802 +Ref: #amounts10940 +Node: Virtual Postings13041 +Ref: #virtual-postings13202 +Node: Balance Assertions14422 +Ref: #balance-assertions14599 +Node: Assertions and ordering15495 +Ref: #assertions-and-ordering15683 +Node: Assertions and included files16383 +Ref: #assertions-and-included-files16626 +Node: Assertions and multiple -f options16959 +Ref: #assertions-and-multiple--f-options17215 +Node: Assertions and commodities17347 +Ref: #assertions-and-commodities17584 +Node: Assertions and subaccounts18280 +Ref: #assertions-and-subaccounts18514 +Node: Assertions and virtual postings19035 +Ref: #assertions-and-virtual-postings19244 +Node: Balance Assignments19386 +Ref: #balance-assignments19555 +Node: Prices20674 +Ref: #prices20809 +Node: Transaction prices20860 +Ref: #transaction-prices21007 +Node: Market prices23163 +Ref: #market-prices23300 +Node: Comments24260 +Ref: #comments24384 +Node: Tags25497 +Ref: #tags25617 +Node: Implicit tags27046 +Ref: #implicit-tags27154 +Node: Directives27671 +Ref: #directives27786 +Node: Account aliases27979 +Ref: #account-aliases28125 +Node: Basic aliases28729 +Ref: #basic-aliases28874 +Node: Regex aliases29564 +Ref: #regex-aliases29734 +Node: Multiple aliases30449 +Ref: #multiple-aliases30623 +Node: end aliases31121 +Ref: #end-aliases31263 +Node: account directive31364 +Ref: #account-directive31546 +Node: apply account directive31842 +Ref: #apply-account-directive32040 +Node: Multi-line comments32699 +Ref: #multi-line-comments32891 +Node: commodity directive33019 +Ref: #commodity-directive33205 +Node: Default commodity34077 +Ref: #default-commodity34252 +Node: Default year34789 +Ref: #default-year34956 +Node: Including other files35379 +Ref: #including-other-files35538 +Node: EDITOR SUPPORT35935 +Ref: #editor-support36055  End Tag Table diff --git a/doc/other/hledger_journal.5.txt b/doc/other/hledger_journal.5.txt --- a/doc/other/hledger_journal.5.txt +++ b/doc/other/hledger_journal.5.txt @@ -53,33 +53,46 @@ FILE FORMAT Transactions - Transactions are represented by journal entries. Each begins with a - simple date in column 0, followed by three optional fields with spaces - between them: + Transactions are movements of some quantity of commodities between + named accounts. Each transaction is represented by a journal entry + beginning with a simple date in column 0. This can be followed by any + of the following, separated by spaces: - o a status flag, which can be empty or ! or * (meaning "uncleared", - "pending" and "cleared", or whatever you want) + o (optional) a status character (empty, !, or *) - o a transaction code (eg a check number), + o (optional) a transaction code (any short number or text, enclosed in + parentheses) - o and/or a description + o (optional) a transaction description (any remaining text until end of + line) - then some number of postings, of some amount to some account. Each - posting is on its own line, consisting of: + Then comes zero or more (but usually at least 2) indented lines repre- + senting... - o indentation of one or more spaces (or tabs) + Postings + A posting is an addition of some amount to, or removal of some amount + from, an account. Each posting line begins with at least one space or + tab (2 or 4 spaces is common), followed by: - o optionally, a ! or * status flag followed by a space + o (optional) a status character (empty, !, or *), followed by a space - o an account name, optionally containing single spaces + o (required) an account name (any text, optionally containing single + spaces, until end of line or a double space) - o optionally, two or more spaces or tabs followed by an amount + o (optional) two or more spaces or tabs followed by an amount. - Usually there are two or more postings, though one or none is also pos- - sible. The posting amounts within a transaction must always balance, - ie add up to 0. Optionally one amount can be left blank, in which case - it will be inferred. + Positive amounts are being added to the account, negative amounts are + being removed. + The amounts within a transaction must always sum up to zero. As a con- + venience, one amount may be left blank; it will be inferred so as to + balance the transaction. + + Be sure to note the unusual two-space delimiter between account name + and amount. This makes it easy to write account names containing spa- + ces. But if you accidentally leave only one space (or tab) before the + amount, the amount will be considered part of the account name. + Dates Simple dates Within a journal file, transaction dates use Y/M/D (or Y-M-D or Y.M.D) @@ -155,14 +168,60 @@ With this syntax, DATE infers its year from the transaction and DATE2 infers its year from DATE. + Status + Transactions, or individual postings within a transaction, can have a + status mark, which is a single character before the transaction + description or posting account name, separated from it by a space, + indicating one of three statuses: + + + mark status + ------------------ + unmarked + ! pending + * cleared + + When reporting, you can filter by status with the -U/--unmarked, + -P/--pending, and -C/--cleared flags; or the status:, status:!, and + status:* queries; or the U, P, C keys in hledger-ui. + + Note, in Ledger and in older versions of hledger, the "unmarked" state + is called "uncleared". As of hledger 1.3 we have renamed it to + unmarked for clarity. + + To replicate Ledger and old hledger's behaviour of also matching pend- + ing, combine -U and -P. + + Status marks are optional, but can be helpful eg for reconciling with + real-world accounts. Some editor modes provide highlighting and short- + cuts for working with status. Eg in Emacs ledger-mode, you can toggle + transaction status with C-c C-e, or posting status with C-c C-c. + + What "uncleared", "pending", and "cleared" actually mean is up to you. + Here's one suggestion: + + + status meaning + -------------------------------------------------------------------------- + uncleared recorded but not yet reconciled; needs review + pending tentatively reconciled (if needed, eg during a big recon- + ciliation) + cleared complete, reconciled as far as possible, and considered + correct + + With this scheme, you would use -PC to see the current balance at your + bank, -U to see things which will probably hit your bank soon (like + uncashed checks), and no flags to see the most up-to-date state of your + finances. + Account names - Account names typically have several parts separated by a full colon, - from which hledger derives a hierarchical chart of accounts. They can - be anything you like, but in finance there are traditionally five - top-level accounts: assets, liabilities, income, expenses, and equity. + Account names typically have several parts separated by a full colon, + from which hledger derives a hierarchical chart of accounts. They can + be anything you like, but in finance there are traditionally five + top-level accounts: assets, liabilities, income, expenses, and equity. - Account names may contain single spaces, eg: assets:accounts receiv- - able. Because of this, they must always be followed by two or more + Account names may contain single spaces, eg: assets:accounts receiv- + able. Because of this, they must always be followed by two or more spaces (or newline). Account names can be aliased. @@ -171,7 +230,7 @@ After the account name, there is usually an amount. Important: between account name and amount, there must be two or more spaces. - Amounts consist of a number and (usually) a currency symbol or commod- + Amounts consist of a number and (usually) a currency symbol or commod- ity name. Some examples: 2.00001 @@ -184,53 +243,53 @@ As you can see, the amount format is somewhat flexible: - o amounts are a number (the "quantity") and optionally a currency sym- + o amounts are a number (the "quantity") and optionally a currency sym- bol/commodity name (the "commodity"). - o the commodity is a symbol, word, or phrase, on the left or right, - with or without a separating space. If the commodity contains num- - bers, spaces or non-word punctuation it must be enclosed in double + o the commodity is a symbol, word, or phrase, on the left or right, + with or without a separating space. If the commodity contains num- + bers, spaces or non-word punctuation it must be enclosed in double quotes. o negative amounts with a commodity on the left can have the minus sign before or after it - o digit groups (thousands, or any other grouping) can be separated by - commas (in which case period is used for decimal point) or periods + o digit groups (thousands, or any other grouping) can be separated by + commas (in which case period is used for decimal point) or periods (in which case comma is used for decimal point) - You can use any of these variations when recording data, but when - hledger displays amounts, it will choose a consistent format for each - commodity. (Except for price amounts, which are always formatted as + You can use any of these variations when recording data, but when + hledger displays amounts, it will choose a consistent format for each + commodity. (Except for price amounts, which are always formatted as written). The display format is chosen as follows: o if there is a commodity directive specifying the format, that is used - o otherwise the format is inferred from the first posting amount in - that commodity in the journal, and the precision (number of decimal + o otherwise the format is inferred from the first posting amount in + that commodity in the journal, and the precision (number of decimal places) will be the maximum from all posting amounts in that commmod- ity - o or if there are no such amounts in the journal, a default format is + o or if there are no such amounts in the journal, a default format is used (like $1000.00). - Price amounts and amounts in D directives usually don't affect amount - format inference, but in some situations they can do so indirectly. - (Eg when D's default commodity is applied to a commodity-less amount, + Price amounts and amounts in D directives usually don't affect amount + format inference, but in some situations they can do so indirectly. + (Eg when D's default commodity is applied to a commodity-less amount, or when an amountless posting is balanced using a price's commodity, or - when -V is used.) If you find this causing problems, set the desired + when -V is used.) If you find this causing problems, set the desired format with a commodity directive. Virtual Postings - When you parenthesise the account name in a posting, we call that a + When you parenthesise the account name in a posting, we call that a virtual posting, which means: o it is ignored when checking that the transaction is balanced - o it is excluded from reports when the --real/-R flag is used, or the + o it is excluded from reports when the --real/-R flag is used, or the real:1 query. - You could use this, eg, to set an account's opening balance without + You could use this, eg, to set an account's opening balance without needing to use the equity:opening balances account: 1/1 special unbalanced posting to set initial balance @@ -238,8 +297,8 @@ When the account name is bracketed, we call it a balanced virtual post- ing. This is like an ordinary virtual posting except the balanced vir- - tual postings in a transaction must balance to 0, like the real post- - ings (but separately from them). Balanced virtual postings are also + tual postings in a transaction must balance to 0, like the real post- + ings (but separately from them). Balanced virtual postings are also excluded by --real/-R or real:1. 1/1 buy food with cash, and update some budget-tracking subaccounts elsewhere @@ -249,13 +308,13 @@ [assets:checking:budget:food] $-10 Virtual postings have some legitimate uses, but those are few. You can - usually find an equivalent journal entry using real postings, which is + usually find an equivalent journal entry using real postings, which is more correct and provides better error checking. 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 + 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: 2013/1/1 @@ -267,31 +326,31 @@ b $-1 =$-2 After reading a journal file, hledger will check all balance assertions - 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 + 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 for reading Ledger files. Assertions and ordering - hledger sorts an account's postings and assertions first by date and - then (for postings on the same day) by parse order. Note this is dif- + hledger sorts an account's postings and assertions first by date and + then (for postings on the same day) by parse order. Note this is dif- ferent from Ledger, which sorts assertions only by parse order. (Also, - Ledger assertions do not see the accumulated effect of repeated post- + Ledger assertions do not see the accumulated effect of repeated post- ings to the same account within a transaction.) - So, hledger balance assertions keep working if you reorder differ- - ently-dated transactions within the journal. But if you reorder + So, hledger balance assertions keep working if you reorder differ- + ently-dated transactions within the journal. But if you reorder same-dated transactions or postings, assertions might break and require - updating. This order dependence does bring an advantage: precise con- + updating. This order dependence does bring an advantage: precise con- trol over the order of postings and assertions within a day, so you can assert intra-day balances. Assertions and included files - With included files, things are a little more complicated. Including - preserves the ordering of postings and assertions. If you have multi- - ple postings to an account on the same day, split across different - files, and you also want to assert the account's balance on the same + With included files, things are a little more complicated. Including + preserves the ordering of postings and assertions. If you have multi- + ple postings to an account on the same day, split across different + files, and you also want to assert the account's balance on the same day, you'll have to put the assertion in the right file. Assertions and multiple -f options @@ -299,21 +358,21 @@ -f options. Use include or concatenate the files instead. Assertions and commodities - The asserted balance must be a simple single-commodity amount, and in - fact the assertion checks only this commodity's balance within the - (possibly multi-commodity) account balance. We could call this a par- - tial balance assertion. This is compatible with Ledger, and makes it + The asserted balance must be a simple single-commodity amount, and in + fact the assertion checks only this commodity's balance within the + (possibly multi-commodity) account balance. We could call this a par- + tial balance assertion. This is compatible with Ledger, and makes it possible to make assertions about accounts containing multiple commodi- ties. - To assert each commodity's balance in such a multi-commodity account, - you can add multiple postings (with amount 0 if necessary). But note - that no matter how many assertions you add, you can't be sure the + To assert each commodity's balance in such a multi-commodity account, + you can add multiple postings (with amount 0 if necessary). But note + that no matter how many assertions you add, you can't be sure the account does not contain some unexpected commodity. (We'll add support for this kind of total balance assertion if there's demand.) Assertions and subaccounts - Balance assertions do not count the balance from subaccounts; they + Balance assertions do not count the balance from subaccounts; they check the posted account's exclusive balance. For example: 1/1 @@ -321,7 +380,7 @@ 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 + The balance report's flat mode shows these exclusive balances more clearly: $ hledger bal checking --flat @@ -335,10 +394,10 @@ tual. They are not affected by the --real/-R flag or real: query. 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 @@ -356,64 +415,75 @@ 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. Prices Transaction prices - Within a transaction posting, you can record an amount's price in - another commodity. This can be used to document the cost (for a pur- - chase), or selling price (for a sale), or the exchange rate that was - used, for this transaction. These transaction prices are fixed, and do - not change over time. + 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. - Amounts with transaction prices can be displayed in the transaction - price's commodity, by using the --cost/-B flag supported by most - hledger commands (mnemonic: "cost Basis"). + Transaction prices are fixed, and do not change over time. (Ledger + users: Ledger uses a different syntax for fixed prices, {=UNITPRICE}, + which hledger currently ignores). There are several ways to record a transaction price: - 1. Write the unit price (aka exchange rate), as @ UNITPRICE after the - amount: + 1. Write the price per unit, as @ UNITPRICE after the amount: 2009/1/1 - assets:foreign currency 100 @ $1.35 ; one hundred euros at $1.35 each - assets:cash + assets:euros 100 @ $1.35 ; one hundred euros purchased at $1.35 each + assets:dollars ; balancing amount is -$135.00 - 2. Or write the total price, as @@ TOTALPRICE after the amount: + 2. Write the total price, as @@ TOTALPRICE after the amount: 2009/1/1 - assets:foreign currency 100 @@ $135 ; one hundred euros at $135 for the lot - assets:cash + assets:euros 100 @@ $135 ; one hundred euros purchased at $135 for the lot + assets:dollars - 3. Or let hledger infer the price so as to balance the transaction. To - permit this, you must fully specify all posting amounts, and their - sum must have a non-zero amount in exactly two commodities: + 3. Specify amounts for all postings, using exactly two commodities, and + let hledger infer the price that balances the transaction: 2009/1/1 - assets:foreign currency 100 ; one hundred euros - assets:cash $-135 ; exchanged for $135 + assets:euros 100 ; one hundred euros purchased + assets:dollars $-135 ; for $135 - With any of the above examples we get: + Amounts with transaction prices can be displayed in the transaction + price's commodity by using the -B/--cost flag (except for #551) ("B" is + from "cost Basis"). Eg for the above, here is how -B affects the bal- + ance report: - $ hledger print -B - 2009/01/01 - assets:foreign currency $135.00 - assets:cash $-135.00 + $ hledger bal -N --flat + $-135 assets:dollars + 100 assets:euros + $ hledger bal -N --flat -B + $-135 assets:dollars + $135 assets:euros # <- the euros' cost - Example use for transaction prices: recording the effective conversion - rate of purchases made in a foreign currency. + 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: + 2009/1/1 + assets:dollars $-135 ; 135 dollars sold + assets:euros 100 ; for 100 euros + + $ hledger bal -N --flat -B + -100 assets:dollars # <- the dollars' selling price + 100 assets:euros + Market prices - Market prices are not tied to a particular transaction; they represent - historical exchange rates between two commodities. (Ledger calls them - historical prices.) For example, the prices published by a stock - exchange or the foreign exchange market. Some commands (balance, cur- - rently) can use this information to show the market value of things at - a given date. + Market prices are not tied to a particular transaction; they represent + historical exchange rates between two commodities. (Ledger calls them + historical prices.) For example, the prices published by a stock + exchange or the foreign exchange market. hledger can use these prices + to show the market value of things at a given date, see market value. To record market prices, use P directives in the main journal or in an included file. Their format is: @@ -560,44 +630,43 @@ Regex aliases There is also a more powerful variant that uses a regular expression, - indicated by the forward slashes. (This was the default behaviour in - hledger 0.24-0.25): + 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. Note, cur- - rently regular expression aliases may cause noticeable slow-downs. + rently regular expression aliases may cause noticeable slow-downs. (And if you use Ledger on your hledger file, they will be ignored.) Eg: alias /^(.+):bank:([^:]+)(.*)/ = \1:\2 \3 # rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking" 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 account directive - The account directive predefines account names, as in Ledger and Bean- - count. This may be useful for your own documentation; hledger doesn't + The account directive predefines account names, as in Ledger and Bean- + count. This may be useful for your own documentation; hledger doesn't make use of it yet. ; account ACCT @@ -612,8 +681,8 @@ ; etc. apply account directive - 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 @@ -630,7 +699,7 @@ 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 @@ -639,16 +708,16 @@ 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. Multi-line comments - A line containing just comment starts a multi-line comment, and a line + A line containing just comment starts a multi-line comment, and a line containing just end comment ends it. See comments. commodity directive - The commodity directive predefines commodities (currently this is just - informational), and also it may define the display format for amounts + The commodity directive predefines commodities (currently this is just + informational), and also it may define the display format for amounts in this commodity (overriding the automatically inferred format). It may be written on a single line, like this: @@ -660,8 +729,8 @@ ; 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 @@ -674,10 +743,10 @@ format INR 9,99,99,999.00 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 @@ -689,8 +758,8 @@ b 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 @@ -710,24 +779,24 @@ assets Including other files - You can pull in the content of additional journal files by writing an + You can pull in the content of additional journal 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 + If the path does not begin with a slash, it is relative to the current file. Glob patterns (*) are not currently supported. - 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. 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 + 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 + These were written with Ledger in mind, but also work with hledger files: @@ -744,7 +813,7 @@ 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) @@ -758,7 +827,7 @@ 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) @@ -766,4 +835,4 @@ -hledger 1.2 March 2017 hledger_journal(5) +hledger 1.3 June 2017 hledger_journal(5) diff --git a/doc/other/hledger_timeclock.5 b/doc/other/hledger_timeclock.5 --- a/doc/other/hledger_timeclock.5 +++ b/doc/other/hledger_timeclock.5 @@ -1,5 +1,5 @@ -.TH "hledger_timeclock" "5" "March 2017" "hledger 1.2" "hledger User Manuals" +.TH "hledger_timeclock" "5" "June 2017" "hledger 1.3" "hledger User Manuals" diff --git a/doc/other/hledger_timeclock.5.info b/doc/other/hledger_timeclock.5.info --- a/doc/other/hledger_timeclock.5.info +++ b/doc/other/hledger_timeclock.5.info @@ -4,7 +4,7 @@  File: hledger_timeclock.5.info, Node: Top, Up: (dir) -hledger_timeclock(5) hledger 1.2 +hledger_timeclock(5) hledger 1.3 ******************************** hledger can read timeclock files. As with Ledger, these are (a subset diff --git a/doc/other/hledger_timeclock.5.txt b/doc/other/hledger_timeclock.5.txt --- a/doc/other/hledger_timeclock.5.txt +++ b/doc/other/hledger_timeclock.5.txt @@ -79,4 +79,4 @@ -hledger 1.2 March 2017 hledger_timeclock(5) +hledger 1.3 June 2017 hledger_timeclock(5) diff --git a/doc/other/hledger_timedot.5 b/doc/other/hledger_timedot.5 --- a/doc/other/hledger_timedot.5 +++ b/doc/other/hledger_timedot.5 @@ -1,5 +1,5 @@ -.TH "hledger_timedot" "5" "March 2017" "hledger 1.2" "hledger User Manuals" +.TH "hledger_timedot" "5" "June 2017" "hledger 1.3" "hledger User Manuals" diff --git a/doc/other/hledger_timedot.5.info b/doc/other/hledger_timedot.5.info --- a/doc/other/hledger_timedot.5.info +++ b/doc/other/hledger_timedot.5.info @@ -4,7 +4,7 @@  File: hledger_timedot.5.info, Node: Top, Next: FILE FORMAT, Up: (dir) -hledger_timedot(5) hledger 1.2 +hledger_timedot(5) hledger 1.3 ****************************** Timedot is a plain text format for logging dated, categorised quantities diff --git a/doc/other/hledger_timedot.5.txt b/doc/other/hledger_timedot.5.txt --- a/doc/other/hledger_timedot.5.txt +++ b/doc/other/hledger_timedot.5.txt @@ -120,4 +120,4 @@ -hledger 1.2 March 2017 hledger_timedot(5) +hledger 1.3 June 2017 hledger_timedot(5) diff --git a/hledger.cabal b/hledger.cabal --- a/hledger.cabal +++ b/hledger.cabal @@ -3,7 +3,7 @@ -- see: https://github.com/sol/hpack name: hledger -version: 1.2 +version: 1.3 synopsis: Command-line interface for the hledger accounting tool description: This is hledger's command-line interface. Its basic function is to read a plain text file describing @@ -80,10 +80,11 @@ library ghc-options: -Wall -fno-warn-unused-do-bind -fno-warn-name-shadowing -fno-warn-missing-signatures -fno-warn-type-defaults -fno-warn-orphans - cpp-options: -DVERSION="1.2" + cpp-options: -DVERSION="1.3" build-depends: base >=4.8 && <5 , base-compat >=0.8.1 + , ansi-terminal >= 0.6.2.3 && < 0.7 , directory , file-embed >=0.0.10 && <0.1 , filepath @@ -92,7 +93,7 @@ , process , temporary , tabular >=0.2 && <0.3 - , hledger-lib >= 1.2 && < 1.3 + , hledger-lib >= 1.3 , bytestring , containers , unordered-containers @@ -105,7 +106,7 @@ , mtl , mtl-compat , old-time - , megaparsec >=5.0 && < 5.3 + , megaparsec >=5.0 && < 5.4 , regex-tdfa , safe >=0.2 , split >=0.1 && <0.3 @@ -165,10 +166,11 @@ hs-source-dirs: app ghc-options: -Wall -fno-warn-unused-do-bind -fno-warn-name-shadowing -fno-warn-missing-signatures -fno-warn-type-defaults -fno-warn-orphans - cpp-options: -DVERSION="1.2" + cpp-options: -DVERSION="1.3" build-depends: base >=4.8 && <5 , base-compat >=0.8.1 + , ansi-terminal >= 0.6.2.3 && < 0.7 , directory , file-embed >=0.0.10 && <0.1 , filepath @@ -177,8 +179,8 @@ , process , temporary , tabular >=0.2 && <0.3 - , hledger-lib >= 1.2 && < 1.3 - , hledger == 1.2 + , hledger-lib >= 1.3 + , hledger == 1.3 , bytestring , containers , unordered-containers @@ -227,10 +229,11 @@ hs-source-dirs: test ghc-options: -Wall -fno-warn-unused-do-bind -fno-warn-name-shadowing -fno-warn-missing-signatures -fno-warn-type-defaults -fno-warn-orphans - cpp-options: -DVERSION="1.2" + cpp-options: -DVERSION="1.3" build-depends: base >=4.8 && <5 , base-compat >=0.8.1 + , ansi-terminal >= 0.6.2.3 && < 0.7 , directory , file-embed >=0.0.10 && <0.1 , filepath @@ -239,8 +242,8 @@ , process , temporary , tabular >=0.2 && <0.3 - , hledger-lib >= 1.2 && < 1.3 - , hledger == 1.2 + , hledger-lib >= 1.3 + , hledger == 1.3 , bytestring , containers , unordered-containers @@ -292,6 +295,7 @@ build-depends: base >=4.8 && <5 , base-compat >=0.8.1 + , ansi-terminal >= 0.6.2.3 && < 0.7 , directory , file-embed >=0.0.10 && <0.1 , filepath @@ -300,8 +304,8 @@ , process , temporary , tabular >=0.2 && <0.3 - , hledger-lib >= 1.2 && < 1.3 - , hledger == 1.2 + , hledger-lib >= 1.3 + , hledger == 1.3 , criterion , html , timeit diff --git a/test/test.hs b/test/test.hs --- a/test/test.hs +++ b/test/test.hs @@ -1,6 +1,13 @@ import Hledger.Cli (tests_Hledger_Cli) +import System.Environment (getArgs) import Test.Framework.Providers.HUnit (hUnitTestToTests) -import Test.Framework.Runners.Console (defaultMain) +import Test.Framework.Runners.Console (defaultMainWithArgs) main :: IO () -main = defaultMain $ hUnitTestToTests tests_Hledger_Cli +main = do + args <- getArgs + let args' = "--hide-successes" : args + defaultMainWithArgs (hUnitTestToTests tests_Hledger_Cli) args' + + +