From 3ec432bd53198866b143e0d43ac3624b421d4977 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Thu, 29 Feb 2024 12:31:07 -1000 Subject: [PATCH 01/41] dev: rename/improve amountSetFullPrecisionUpTo, add mixedAmountSetFullPrecisionUpTo --- hledger-lib/Hledger/Data/Amount.hs | 39 +++++++++++++++++--------- hledger-lib/Hledger/Data/Valuation.hs | 4 +-- hledger/Hledger/Cli/Commands/Prices.hs | 2 +- hledger/Hledger/Cli/Commands/Roi.hs | 2 +- 4 files changed, 29 insertions(+), 18 deletions(-) diff --git a/hledger-lib/Hledger/Data/Amount.hs b/hledger-lib/Hledger/Data/Amount.hs index 2aec34e9d..844ad4431 100644 --- a/hledger-lib/Hledger/Data/Amount.hs +++ b/hledger-lib/Hledger/Data/Amount.hs @@ -97,7 +97,7 @@ module Hledger.Data.Amount ( amountSetPrecisionMax, withPrecision, amountSetFullPrecision, - amountSetFullPrecisionOr, + amountSetFullPrecisionUpTo, amountInternalPrecision, amountDisplayPrecision, defaultMaxPrecision, @@ -159,6 +159,7 @@ module Hledger.Data.Amount ( wbUnpack, mixedAmountSetPrecision, mixedAmountSetFullPrecision, + mixedAmountSetFullPrecisionUpTo, mixedAmountSetPrecisionMin, mixedAmountSetPrecisionMax, @@ -453,24 +454,26 @@ amountSetFullPrecision a = amountSetPrecision p a -- | We often want to display "infinite decimal" amounts rounded to some readable --- number of digits, while still displaying amounts with a large "non infinite" number --- of decimal digits (eg, 100 or 200 digits) in full. +-- number of digits, while still displaying amounts with a large but "non infinite" +-- number of decimal digits (eg 10 or 100 or 200 digits) in full. -- This helper is like amountSetFullPrecision, but with some refinements: --- 1. If the internal precision is the maximum (255), indicating an infinite decimal, --- the display precision is set to a smaller hard-coded default (8). --- 2. A maximum display precision can be specified, setting a hard upper limit. +-- +-- 1. A maximum display precision can be specified, setting a hard upper limit. +-- +-- 2. If no limit is specified, and the internal precision is the maximum (255), +-- indicating an infinite decimal, display precision is set to a smaller default (8). +-- -- This function always sets an explicit display precision (ie, Precision n). -amountSetFullPrecisionOr :: Maybe Word8 -> Amount -> Amount -amountSetFullPrecisionOr mmaxp a = amountSetPrecision (Precision p2) a +-- +amountSetFullPrecisionUpTo :: Maybe Word8 -> Amount -> Amount +amountSetFullPrecisionUpTo mmaxp a = amountSetPrecision (Precision p) a where - p1 = if -- dbg0 "maxdigits" $ - amountHasMaxDigits a then defaultMaxPrecision else max disp intp - -- & dbg0 "p1" + p = case mmaxp of + Just maxp -> min maxp $ max disp intp + Nothing -> if amountHasMaxDigits a then defaultMaxPrecision else max disp intp where - intp = amountInternalPrecision a disp = amountDisplayPrecision a - p2 = maybe p1 (min p1) mmaxp - -- & dbg0 "p2" + intp = amountInternalPrecision a -- | The fallback display precision used when showing amounts -- representing an infinite decimal. @@ -1228,6 +1231,14 @@ mixedAmountSetPrecision p = mapMixedAmountUnsafe (amountSetPrecision p) mixedAmountSetFullPrecision :: MixedAmount -> MixedAmount mixedAmountSetFullPrecision = mapMixedAmountUnsafe amountSetFullPrecision +-- | In each component amount, increase the display precision sufficiently +-- to render it exactly if possible, but not more than the given max precision, +-- and if no max precision is given and the amount has infinite decimals, +-- limit display precision to a hard-coded smaller number (8). +-- See amountSetFullPrecisionUpTo. +mixedAmountSetFullPrecisionUpTo :: Maybe Word8 -> MixedAmount -> MixedAmount +mixedAmountSetFullPrecisionUpTo mmaxp = mapMixedAmountUnsafe (amountSetFullPrecisionUpTo mmaxp) + -- | In each component amount, ensure the display precision is at least the given value. -- Makes all amounts have an explicit Precision. mixedAmountSetPrecisionMin :: Word8 -> MixedAmount -> MixedAmount diff --git a/hledger-lib/Hledger/Data/Valuation.hs b/hledger-lib/Hledger/Data/Valuation.hs index 7e174e347..614f59a4d 100644 --- a/hledger-lib/Hledger/Data/Valuation.hs +++ b/hledger-lib/Hledger/Data/Valuation.hs @@ -115,7 +115,7 @@ amountPriceDirectiveFromCost :: Day -> Amount -> Maybe PriceDirective amountPriceDirectiveFromCost d amt@Amount{acommodity=fromcomm, aquantity=n} = case acost amt of Just (UnitCost u) -> Just $ pd{pdamount=u} Just (TotalCost t) | n /= 0 -> Just $ pd{pdamount=u} - where u = amountSetFullPrecisionOr Nothing $ divideAmount n t + where u = amountSetFullPrecisionUpTo Nothing $ divideAmount n t _ -> Nothing where pd = PriceDirective{pddate = d, pdcommodity = fromcomm, pdamount = nullamt} @@ -209,7 +209,7 @@ amountValueAtDate priceoracle styles mto d a = -- set the display precision to match the internal precision (showing all digits), -- unnormalised (don't strip trailing zeros); -- but if it looks like an infinite decimal, limit the precision to 8. - & amountSetFullPrecisionOr Nothing + & amountSetFullPrecisionUpTo Nothing & dbg9With (lbl "calculated value".showAmount) -- | Calculate the gain of each component amount, that is the difference diff --git a/hledger/Hledger/Cli/Commands/Prices.hs b/hledger/Hledger/Cli/Commands/Prices.hs index 0d46899d9..65ac476f1 100644 --- a/hledger/Hledger/Cli/Commands/Prices.hs +++ b/hledger/Hledger/Cli/Commands/Prices.hs @@ -107,7 +107,7 @@ reversePriceDirective pd@PriceDirective{pdcommodity=c, pdamount=a} where lbl = lbl_ "reversePriceDirective" a' = - amountSetFullPrecisionOr (Just defaultMaxPrecision) $ + amountSetFullPrecisionUpTo (Just defaultMaxPrecision) $ invertAmount a{acommodity=c} & dbg9With (lbl "calculated reverse price".showAmount) -- & dbg9With (lbl "precision of reverse price".show.amountDisplayPrecision) diff --git a/hledger/Hledger/Cli/Commands/Roi.hs b/hledger/Hledger/Cli/Commands/Roi.hs index 0ec91c5a4..28c1bb9a3 100644 --- a/hledger/Hledger/Cli/Commands/Roi.hs +++ b/hledger/Hledger/Cli/Commands/Roi.hs @@ -147,7 +147,7 @@ roi CliOpts{rawopts_=rawopts, reportspec_=rspec@ReportSpec{_rsReportOpts=ReportO , T.pack $ showMixedAmount $ styleAmounts styles $ cashFlowAmt -- , T.pack $ showMixedAmount $ -- -- dbg0With (lbl "cashflow after styling".showMixedAmountOneLine) $ - -- mapMixedAmount (amountSetFullPrecisionOr (Just defaultMaxPrecision)) $ + -- mapMixedAmount (amountSetFullPrecisionUpTo (Just defaultMaxPrecision)) $ -- styleAmounts (styles -- -- & dbg0With (lbl "styles".show)) -- cashFlowAmt From 1ee0e8071959a436b097d01897e8771ebf8215f6 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Thu, 29 Feb 2024 12:32:23 -1000 Subject: [PATCH 02/41] imp:errors:unbalanced transaction: show more precise amounts (#2135) Like we used to in 1.30, but better (show all available decimal digits, unless they're infinite in which case show 8, show trailing zeros, show commodity symbol with zero). --- hledger-lib/Hledger/Data/Balancing.hs | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/hledger-lib/Hledger/Data/Balancing.hs b/hledger-lib/Hledger/Data/Balancing.hs index 031a6e888..5f3c9767c 100644 --- a/hledger-lib/Hledger/Data/Balancing.hs +++ b/hledger-lib/Hledger/Data/Balancing.hs @@ -131,11 +131,17 @@ transactionCheckBalanced BalancingOpts{commodity_styles_} t = errs rmsg | rsumok = "" | not rsignsok = "The real postings all have the same sign. Consider negating some of them." - | otherwise = "The real postings' sum should be 0 but is: " ++ showMixedAmountOneLineWithoutCost False rsumcost + | otherwise = "The real postings' sum should be 0 but is: " ++ + (showMixedAmountWith oneLineNoCostFmt{displayCost=True, displayZeroCommodity=True} $ + mixedAmountSetFullPrecisionUpTo Nothing $ mixedAmountSetFullPrecision + rsumcost) bvmsg | bvsumok = "" | not bvsignsok = "The balanced virtual postings all have the same sign. Consider negating some of them." - | otherwise = "The balanced virtual postings' sum should be 0 but is: " ++ showMixedAmountOneLineWithoutCost False bvsumcost + | otherwise = "The balanced virtual postings' sum should be 0 but is: " ++ + (showMixedAmountWith oneLineNoCostFmt{displayCost=True, displayZeroCommodity=True} $ + mixedAmountSetFullPrecisionUpTo Nothing $ mixedAmountSetFullPrecision + bvsumcost) -- | Legacy form of transactionCheckBalanced. isTransactionBalanced :: BalancingOpts -> Transaction -> Bool From a6db6762ac09bf04480ea9a60251e12f10da3deb Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Thu, 29 Feb 2024 14:52:19 -1000 Subject: [PATCH 03/41] ;doc:journal:transactions: edits; mention debits and credits and sign --- hledger/hledger.m4.md | 49 +++++++++++++++++++++++++++---------------- 1 file changed, 31 insertions(+), 18 deletions(-) diff --git a/hledger/hledger.m4.md b/hledger/hledger.m4.md index 5637603c4..d341ca649 100644 --- a/hledger/hledger.m4.md +++ b/hledger/hledger.m4.md @@ -932,8 +932,7 @@ See Transaction comments, Posting comments, and Account comments below. ## Transactions Transactions are the main unit of information in a journal file. -They represent events, typically a movement of some quantity of -commodities between two or more named accounts. +They represent events, typically a movement of some quantity of commodities between two or more named accounts. Each transaction is recorded as a journal entry, beginning with a [simple date](#simple-dates) in column 0. This can be followed by any @@ -1001,9 +1000,9 @@ eg a `date:` tag with no value is not allowed. ## Status -Transactions, or individual postings within a transaction, +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, +the transaction description (or posting account name), separated from it by a space, indicating one of three statuses: | mark   | status | @@ -1013,14 +1012,13 @@ separated from it by a space, indicating one of three statuses: | `*` | 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](#queries); +the `-U/--unmarked`, `-P/--pending`, and `-C/--cleared` flags +(and you can combine these, eg `-UP` to match all except cleared things). +Or you can use the `status:`, `status:!`, and `status:*` [queries](#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. +(Note: in Ledger the "unmarked" state is called "uncleared"; +in hledger we renamed it to "unmarked" for semantic clarity.) 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. @@ -1101,16 +1099,31 @@ Each posting line begins with at least one space or tab (2 or 4 spaces is common - (optional) a [status](#status) character (empty, `!`, or `*`), followed by a space - (required) an [account name](#account-names) (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](#amounts). +- (optional) **two or more spaces** (or tabs) followed by an [amount](#amounts). -Positive amounts are being added to the account, negative amounts are being removed. +If the amount is positive, it is being added to the account; +if negative, it is being removed from the account. -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. +The posting amounts in a transaction must sum up to zero, indicating that the inflows and outflows are equal. We call this a balanced transaction. +(You can read more about the nitty-gritty details of "sum up to zero" in [Transaction balancing](#transaction-balancing) below.) -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. +As a convenience, you can optionally leave one amount blank; hledger will infer what it should be so as to balance the transaction. + +### Debits and credits + +These traditional accounting concepts of debit and credit of course exist in hledger, but we represent them with numeric sign, as described above. +Positive and negative posting amounts represent debits and credits respectively. + +You don't need to remember that, but if you would like to - eg for helping newcomers or for talking with your accountant - here's a handy mnemonic: + +*`debit / plus / left / short words`*\ +*`credit / minus / right / longer words`* + +### The two space delimiter + +Be sure to notice the unusual separator between the account name and the following amount. +Because hledger allows account names with spaces in them, you must separate the account name and amount (if any) by **two or more spaces** (or tabs). +It's easy to forget at first. If you ever see the amount being treated as part of the account name, you'll know you probably need to add another space between them. ## Account names @@ -1321,7 +1334,7 @@ for details, see [Amount formatting, parseability](#amount-formatting-parseabili -## Costs +### Costs After a posting amount, you can note its cost (when buying) or selling price (when selling) in another commodity, by writing either `@ UNITPRICE` or `@@ TOTALPRICE` after it. From 2ccbb16f07566100d1c40ef65b6595c634195765 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Thu, 29 Feb 2024 14:52:52 -1000 Subject: [PATCH 04/41] ;doc:journal:transactions: explain transaction balancing (#2135) --- hledger/hledger.m4.md | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/hledger/hledger.m4.md b/hledger/hledger.m4.md index d341ca649..621aedcc5 100644 --- a/hledger/hledger.m4.md +++ b/hledger/hledger.m4.md @@ -1631,6 +1631,34 @@ except they may contain [tags](#tags), which are not ignored. ; a second comment line for posting 2 ``` +## Transaction balancing + +How exactly does hledger decide when a transaction is balanced ? +The general goal is that if you look at the journal entry and calculate the amounts' +sum perfectly with pencil and paper, hledger should agree with you. + +Real world transactions, especially for investments or cryptocurrencies, +often involve imprecise costs, complex decimals, and/or infinitely-recurring decimals, +which are difficult or inconvenient to handle on a computer. +So to be a practical accounting system, hledger allows some imprecision when checking transaction balancedness. +The question is, how much imprecision should be allowed ? + +hledger currently decides it based on the commodity display precisions inferred or declared for each commodity: +if the postings' sum would appear to be zero when displayed with the standard display precisions, the transaction is considered balanced. + +Or equivalently: if the journal entry is displayed with amounts rounded to the +standard display precisions (with `hledger print --round=hard`), and a human with +pencil and paper would agree that those displayed amounts add up to zero, +the transaction is considered balanced. + +This has some advantages: it is general, usually intuitive, and configurable when needed. +It means that transaction balancedness is somewhat dependent on commodity display precisions, +so eg when using `-c/--commodity-style` to display things with more than usual precision, +you could notice some of your journal entries need to adjusted (made more precise). + +Other PTA tools (Ledger, Beancount..) have their own ways of doing it. +Possible improvements are discussed at [#1964](https://github.com/simonmichael/hledger/issues/1964). + ## Tags From 62151d679e5c37573ff50541eb3de2475fdaf7ed Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Thu, 29 Feb 2024 15:05:41 -1000 Subject: [PATCH 05/41] ;doc:journal: move intro before cheatsheet --- hledger/hledger.m4.md | 138 ++++++++++++++++++++---------------------- 1 file changed, 67 insertions(+), 71 deletions(-) diff --git a/hledger/hledger.m4.md b/hledger/hledger.m4.md index 621aedcc5..f396d699d 100644 --- a/hledger/hledger.m4.md +++ b/hledger/hledger.m4.md @@ -740,9 +740,73 @@ unless overridden by an explicit `--color/--colour` option. # Journal -hledger's default file format, representing a General Journal. -Here's a cheatsheet/mini-tutorial, -or you can skip ahead to [About journal format](#about-journal-format). +hledger's usual data source is a plain text file containing journal entries in hledger `journal` format. +If you're looking for a quick reference, jump ahead to the +[journal cheatsheet](#journal-cheatsheet) (or use the table of contents at ). + +This file represents an accounting [General Journal](http://en.wikipedia.org/wiki/General_journal). +The `.journal` file extension is most often used, though not strictly required. +The journal file contains a number of transaction entries, +each describing a transfer of money (or any commodity) between two or more named accounts, +in a simple format readable by both hledger and humans. + +hledger's journal format is compatible with most of +[Ledger's journal format](http://ledger-cli.org/3.0/doc/ledger3.html#Journal-Format), but not all of it. +The differences and interoperation tips are described at [hledger and Ledger](ledger.html). +With some care, and by avoiding incompatible features, you can keep your hledger journal +readable by Ledger and vice versa. This can useful eg for comparing the behaviour of one app +against the other. + +You can use hledger without learning any more about this file; just +use the [add](#add) or [web](#web) or [import](#import) commands to +create and update it. + +Many users, though, edit the journal file with a text editor, +and track changes with a version control system such as git. +Editor addons such as +ledger-mode or hledger-mode for Emacs, +vim-ledger for Vim, +and hledger-vscode for Visual Studio Code, +make this easier, adding colour, formatting, tab completion, and useful commands. +See [Editor configuration](/editors.html) at hledger.org for the full list. + + + +A hledger journal file can contain three kinds of thing: +comment lines, transactions, and/or directives (including periodic transaction rules and auto posting rules). +Understanding the journal file format will also give you a good understanding of hledger's data model. +Here's a quick cheatsheet/overview, followed by detailed descriptions of each part. ## Journal cheatsheet @@ -837,74 +901,6 @@ P 2022-01-01 AAAA $1.40 12/31 also allowed (but consistent YYYY-MM-DD is recommended). ``` -## About journal format - -hledger's usual data source is a plain text file containing journal entries in hledger journal format. -This file represents a standard accounting [general journal](http://en.wikipedia.org/wiki/General_journal). -I use file names ending in `.journal`, but that's not required. -The journal file contains a number of transaction entries, -each describing a transfer of money (or any commodity) between two or more named accounts, -in a simple format readable by both hledger and humans. - -hledger's journal format is compatible with most of -[Ledger's journal format](http://ledger-cli.org/3.0/doc/ledger3.html#Journal-Format), but not all of it. -The differences and interoperation tips are described at [hledger and Ledger](ledger.html). -With some care, and by avoiding incompatible features, you can keep your hledger journal -readable by Ledger and vice versa. This can useful eg for comparing the behaviour of one app -against the other. - -You can use hledger without learning any more about this file; just -use the [add](#add) or [web](#web) or [import](#import) commands to -create and update it. - -Many users, though, edit the journal file with a text editor, -and track changes with a version control system such as git. -Editor addons such as -ledger-mode or hledger-mode for Emacs, -vim-ledger for Vim, -and hledger-vscode for Visual Studio Code, -make this easier, adding colour, formatting, tab completion, and useful commands. -See [Editor configuration](/editors.html) at hledger.org for the full list. - - - -Here's a description of each part of the file format (and hledger's data model). - -A hledger journal file can contain three kinds of thing: -file comments, transactions, and/or directives -(counting periodic transaction rules and auto posting rules as directives). - ## Comments Lines in the journal will be ignored if they begin with a hash (`#`) or a semicolon (`;`). (See also [Other syntax](#other-syntax).) From 86ba7cc3a3a122596173da7b1f070de1d9db8be9 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Thu, 29 Feb 2024 15:31:44 -1000 Subject: [PATCH 06/41] ;doc:journal:amounts/commodities/numbers: cleanup --- hledger/hledger.m4.md | 59 ++++++++++++++++++++----------------------- 1 file changed, 27 insertions(+), 32 deletions(-) diff --git a/hledger/hledger.m4.md b/hledger/hledger.m4.md index f396d699d..98a230866 100644 --- a/hledger/hledger.m4.md +++ b/hledger/hledger.m4.md @@ -1236,8 +1236,18 @@ In such cases hledger assumes it is a decimal mark, parsing both of these as 1. To disambiguate these and ensure accurate number parsing, especially if you use digit group marks, we recommend declaring the decimal mark. You can declare it for each file with [`decimal-mark`](#decimal-mark-directive) directives, -or for each commodity with [`commodity`](#commodity-directive) directives -(described below). +or for each commodity with [`commodity`](#commodity-directive) directives, +described below. +A quick example: + +```journal +# Assume . is the decimal mark used by all amounts in this file (in all commodities) +decimal-mark . +``` + +Note, hledger accepts numbers with no digits after the decimal mark, like `10.`. +(And will sometimes display numbers that way to disambiguate them - see +[Amount formatting, parseability](#amount-formatting-parseability).) ### Commodity @@ -1258,26 +1268,7 @@ the time. A multi-commodity amount could be, eg: `1 USD, 2 EUR, 3.456 TSLA`. In practice, you will only see multi-commodity amounts in hledger's output; you can't write them directly in the journal file. - -(If you are writing scripts or working with hledger's internals, these -are the `Amount` and `MixedAmount` types.) - -### Directives influencing number parsing and display - -You can add `decimal-mark` and `commodity` directives to the journal, -to declare and control these things more explicitly and precisely. -These are described below, but here's a quick example: - -```journal -# the decimal mark character used by all amounts in this file (all commodities) -decimal-mark . - -# display styles for the $, EUR, INR and no-symbol commodities: -commodity $1,000.00 -commodity EUR 1.000,00 -commodity INR 9,99,99,999.00 -commodity 1 000 000.9455 -``` + @@ -1295,11 +1286,21 @@ Then each commodity's display style is determined from its declaring commodities with `commodity` directives, since they help ensure consistent display styles and precisions, and bring other benefits such as error checking for commodity symbols. +Here's an example: -But if a `commodity` directive is not present, hledger infers a -commodity's display styles from its amounts as they are written in the -journal (excluding cost amounts and amounts in periodic transaction -rules or auto posting rules). It uses +```journal +# Set display styles (and decimal marks, for parsing, if there is no decimal-mark directive) +# for the $, EUR, INR and no-symbol commodities: +commodity $1,000.00 +commodity EUR 1.000,00 +commodity INR 9,99,99,999.00 +commodity 1 000 000.9455 +``` + +But for convenience, if a `commodity` directive is not present, +hledger infers a commodity's display styles from its amounts as they are written in the journal +(excluding cost amounts and amounts in periodic transaction rules or auto posting rules). +It uses - the symbol placement and decimal mark of the first amount seen - the digit group marks of the first amount with digit group marks @@ -1322,12 +1323,6 @@ by other reports. When rounding, hledger uses [banker's rounding](https://en.wikipedia.org/wiki/Bankers_rounding) (it rounds to the nearest even digit). So eg 0.5 displayed with zero decimal digits appears as "0". -### Number format - -hledger will occasionally make some additional adjustments to number formatting, -eg adding a trailing decimal mark to disambiguate numbers with digit group marks; -for details, see [Amount formatting, parseability](#amount-formatting-parseability). - ### Costs From 90c824adaa750e42f987a797de1c33d33030d355 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Thu, 29 Feb 2024 15:34:48 -1000 Subject: [PATCH 07/41] ;doc:journal:transactions: typo --- hledger/hledger.m4.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/hledger/hledger.m4.md b/hledger/hledger.m4.md index 98a230866..86bc75718 100644 --- a/hledger/hledger.m4.md +++ b/hledger/hledger.m4.md @@ -1107,7 +1107,7 @@ As a convenience, you can optionally leave one amount blank; hledger will infer ### Debits and credits -These traditional accounting concepts of debit and credit of course exist in hledger, but we represent them with numeric sign, as described above. +The traditional accounting concepts of debit and credit of course exist in hledger, but we represent them with numeric sign, as described above. Positive and negative posting amounts represent debits and credits respectively. You don't need to remember that, but if you would like to - eg for helping newcomers or for talking with your accountant - here's a handy mnemonic: From 8225b3dcefb9c6cb4330c10d9038174dd36a830d Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Thu, 29 Feb 2024 16:06:46 -1000 Subject: [PATCH 08/41] ;doc:journal:commodity directive: clarify & fix scope of effects (#2135) --- hledger/hledger.m4.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/hledger/hledger.m4.md b/hledger/hledger.m4.md index 86bc75718..9869ed24d 100644 --- a/hledger/hledger.m4.md +++ b/hledger/hledger.m4.md @@ -1790,7 +1790,8 @@ Here are all hledger's directives, with their effects and scope summarised - nin | **[`account`]** | Declares an account, for [checking](#check) all entries in all files;
and its [display order](#account-display-order) and [type](#declaring-account-types).
Subdirectives: any text, ignored. | N | | **[`alias`]** | Rewrites account names, in following entries until end of current file or [`end aliases`].
Command line equivalent: [`--alias`] | Y | | **[`comment`]** | Ignores part of the journal file, until end of current file or `end comment`. | Y | -| **[`commodity`]** | Declares up to four things:
1. a commodity symbol, for checking all amounts in all files
2. the decimal mark for parsing amounts of this commodity, in the following entries until end of current file (if there is no `decimal-mark` directive)
3. and the display style for amounts of this commodity
4. which is also the precision to use for balanced-transaction checking in this commodity.
Takes precedence over `D`.
Subdirectives: `format` (Ledger-compatible syntax).
Command line equivalent: [`-c/--commodity-style`](#commodity-styles) | N,
Y,
N,
N | +| **[`commodity`]** | Declares up to four things: +
1. a commodity symbol, for checking all amounts in all files
2. the display style for all amounts of this commodity
3. the decimal mark for parsing amounts of this commodity, in the rest of this file and its children, if there is no `decimal-mark` directive
4. the precision to use for balanced-transaction checking in this commodity, in this file and its children.
Takes precedence over `D`.
Subdirectives: `format` (ignored).
Command line equivalent: [`-c/--commodity-style`](#commodity-styles) | N,
N,
Y,
Y | | **[`decimal-mark`]** | Declares the decimal mark, for parsing amounts of all commodities in following entries until next `decimal-mark` or end of current file. Included files can override. Takes precedence over `commodity` and `D`. | Y | | **[`include`]** | Includes entries and directives from another file, as if they were written inline.
Command line alternative: multiple [`-f/--file`](#multiple-files) | N | | **[`payee`]** | Declares a payee name, for checking all entries in all files. | N | @@ -2200,23 +2201,22 @@ The `commodity` directive performs several functions: 1. It declares which commodity symbols may be used in the journal, enabling useful error checking with [strict mode] or the check command. - (See [Commodity error checking](#commodity-error-checking) below.) + See [Commodity error checking](#commodity-error-checking) below. -2. It declares the precision with which this commodity's amounts - should be compared when checking for balanced transactions. +2. It declares how all amounts in this commodity should be displayed, eg how many decimals to show. + See [Commodity display style](#commodity-display-style) above. -3. It declares how this commodity's amounts should be displayed, - eg their symbol placement, digit group mark if any, digit group sizes, - decimal mark (period or comma), and the number of decimal places. - (See [Commodity display style](#commodity-display-style) above.) - -4. It sets which decimal mark (period or comma) to expect when parsing subsequent amounts in this commodity - (if there is no `decimal-mark` directive in effect. +3. (If no `decimal-mark` directive is in effect:) + It sets the decimal mark to expect (period or comma) when parsing amounts in this commodity, + in this file and files it includes, from the directive until end of current file. See [Decimal marks, digit group marks](hledger.md#decimal-marks-digit-group-marks) above. - For related dev discussion, see [#793](https://github.com/simonmichael/hledger/issues/793).) + +4. It declares the precision with which this commodity's amounts should be compared when checking for balanced transactions, + anywhere in this file and files it includes, until end of current file. Declaring commodities solves several common parsing/display problems, so we recommend it. -Generally you should put `commodity` directives at the top of your journal file (because function 4 is position-sensitive). + +(Related dev discussion: [#793](https://github.com/simonmichael/hledger/issues/793).) ### Commodity directive syntax From d0c0a3f72c1446a4c3d52a6e0ab1fe22fd123a6a Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Thu, 29 Feb 2024 16:12:32 -1000 Subject: [PATCH 09/41] ;doc:journal:transaction balancing: edits --- hledger/hledger.m4.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/hledger/hledger.m4.md b/hledger/hledger.m4.md index 9869ed24d..b16c0fe1a 100644 --- a/hledger/hledger.m4.md +++ b/hledger/hledger.m4.md @@ -1642,10 +1642,10 @@ standard display precisions (with `hledger print --round=hard`), and a human wit pencil and paper would agree that those displayed amounts add up to zero, the transaction is considered balanced. -This has some advantages: it is general, usually intuitive, and configurable when needed. -It means that transaction balancedness is somewhat dependent on commodity display precisions, +This has some advantages: it is fairly intuitive, general not hard-coded, yet configurable when needed. +On the downside it means that transaction balancedness is related to commodity display precisions, so eg when using `-c/--commodity-style` to display things with more than usual precision, -you could notice some of your journal entries need to adjusted (made more precise). +you might need to fix some of your journal entries (ie, add decimal digits to make them balance more precisely). Other PTA tools (Ledger, Beancount..) have their own ways of doing it. Possible improvements are discussed at [#1964](https://github.com/simonmichael/hledger/issues/1964). From 81f9b51967f8e13e0a00caeba9a79c3c15a272df Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Thu, 29 Feb 2024 16:16:23 -1000 Subject: [PATCH 10/41] ;doc:journal: edits --- hledger/hledger.m4.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/hledger/hledger.m4.md b/hledger/hledger.m4.md index b16c0fe1a..5e04d9d4e 100644 --- a/hledger/hledger.m4.md +++ b/hledger/hledger.m4.md @@ -1168,7 +1168,7 @@ Account names can be altered temporarily or permanently by [account aliases](#al ## Amounts After the account name, there is usually an amount. -(Important: between account name and amount, there must be **two or more spaces**.) +(Remember: between account name and amount, there must be two or more spaces.) hledger's amount format is flexible, supporting several international formats. Here are some examples. From ed3dc344fc47ee8895486620ef991bda87948dd1 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Thu, 29 Feb 2024 16:31:26 -1000 Subject: [PATCH 11/41] ;doc:journal: split Decimal marks, Digit group marks --- hledger/hledger.m4.md | 66 +++++++++++++++++++++++-------------------- 1 file changed, 35 insertions(+), 31 deletions(-) diff --git a/hledger/hledger.m4.md b/hledger/hledger.m4.md index 5e04d9d4e..feb04c6b4 100644 --- a/hledger/hledger.m4.md +++ b/hledger/hledger.m4.md @@ -589,7 +589,7 @@ Some notes about the various output formats: ### CSV output -- In CSV output, [digit group marks](#decimal-marks-digit-group-marks) (such as thousands separators) +- In CSV output, [digit group marks](#digit-group-marks) (such as thousands separators) are disabled automatically. ### HTML output @@ -1201,15 +1201,39 @@ Scientific E notation is allowed: 1E-6 EUR 1E3 -### Decimal marks, digit group marks + + +### Decimal marks A *decimal mark* can be written as a period or a comma: 1.23 1,23 -In the integer part of the quantity (left of the decimal mark), groups -of digits can optionally be separated by a *digit group mark* - +Both of these are common in [international number formats][international number formats], +so hledger is not biased towards one or the other. +Because hledger also supports digit group marks (eg thousands separators), +this means that a number like `1,000` or `1.000` containing just one period or comma is ambiguous. +In such cases, hledger by default assumes it is a decimal mark, and will parse both of those as 1. + +[international number formats]: https://en.wikipedia.org/wiki/Decimal_separator#Conventions_worldwide + +To help hledger parse such ambiguous numbers more accurately, +if you use digit group marks, we recommend declaring the decimal mark explicitly. +The best way is to add a [`decimal-mark`](#decimal-mark-directive) directive at the top of each data file, like this: +```journal +decimal-mark . +``` +Or you can declare it per commodity with [`commodity`](#commodity-directive) directives, described below. + +hledger also accepts numbers like `10.` with no digits after the decimal mark +(and will sometimes display numbers that way to disambiguate them - see +[Amount formatting, parseability](#amount-formatting-parseability)). + +### Digit group marks + +In the integer part of the amount quantity (left of the decimal mark), +groups of digits can optionally be separated by a *digit group mark* - a comma or period (whichever is not used as decimal mark), or a space (any of these Unicode space characters: space, @@ -1221,33 +1245,13 @@ thin space, narrow no-break space, medium mathematical space). +So these are all valid amounts in a journal file: + $1,000,000.00 EUR 2.000.000,00 INR 9,99,99,999.00 - 1 000 000.00 <- ordinary space - 1 000 000.00 <- no-break space - -hledger is not biased towards [period or comma decimal marks][international number formats], -so a number containing just one period or comma, like `1,000` or `1.000`, is ambiguous. -In such cases hledger assumes it is a decimal mark, parsing both of these as 1. - -[international number formats]: https://en.wikipedia.org/wiki/Decimal_separator#Conventions_worldwide - -To disambiguate these and ensure accurate number parsing, especially -if you use digit group marks, we recommend declaring the decimal mark. -You can declare it for each file with [`decimal-mark`](#decimal-mark-directive) directives, -or for each commodity with [`commodity`](#commodity-directive) directives, -described below. -A quick example: - -```journal -# Assume . is the decimal mark used by all amounts in this file (in all commodities) -decimal-mark . -``` - -Note, hledger accepts numbers with no digits after the decimal mark, like `10.`. -(And will sometimes display numbers that way to disambiguate them - see -[Amount formatting, parseability](#amount-formatting-parseability).) + 1 000 000.00 ; <- ordinary space + 1 000 000.00 ; <- no-break space ### Commodity @@ -2209,7 +2213,7 @@ The `commodity` directive performs several functions: 3. (If no `decimal-mark` directive is in effect:) It sets the decimal mark to expect (period or comma) when parsing amounts in this commodity, in this file and files it includes, from the directive until end of current file. - See [Decimal marks, digit group marks](hledger.md#decimal-marks-digit-group-marks) above. + See [Decimal marks](#decimal-marks) above. 4. It declares the precision with which this commodity's amounts should be compared when checking for balanced transactions, anywhere in this file and files it includes, until end of current file. @@ -2290,7 +2294,7 @@ or decimal-mark , ``` -This prevents any [ambiguity](#decimal-marks-digit-group-marks) when +This prevents any [ambiguity](#decimal-mark) when parsing numbers in the file, so we recommend it, especially if the file contains digit group marks (eg thousands separators). @@ -4523,7 +4527,7 @@ If you're wondering why your [`print`](#print) report sometimes shows trailing decimal marks, with no decimal digits; it does this when showing amounts that have digit group marks but no decimal digits, to disambiguate them and allow them to be re-parsed reliably -(see also [Decimal marks, digit group marks](#decimal-marks-digit-group-marks). +(see also [Decimal marks](#decimal-marks). Eg: ```journal From 256294101d41fa1b0930f5142f36965d82225933 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Thu, 29 Feb 2024 16:35:45 -1000 Subject: [PATCH 12/41] ;doc:journal:Digit group marks: simplify, don't encourage mad unicode spaces --- hledger/hledger.m4.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/hledger/hledger.m4.md b/hledger/hledger.m4.md index feb04c6b4..3f17005dc 100644 --- a/hledger/hledger.m4.md +++ b/hledger/hledger.m4.md @@ -1235,7 +1235,8 @@ hledger also accepts numbers like `10.` with no digits after the decimal mark In the integer part of the amount quantity (left of the decimal mark), groups of digits can optionally be separated by a *digit group mark* - a comma or period (whichever is not used as decimal mark), -or a space (any of these Unicode space characters: +or a space (several Unicode space variants, like no-break space, are also accepted). + So these are all valid amounts in a journal file: $1,000,000.00 From b39948a3dd89ce259d7cbf6b7a7bc7ff98d85cf2 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Thu, 29 Feb 2024 16:53:20 -1000 Subject: [PATCH 13/41] ;doc:journal: move complex discussion of commodity styles later --- hledger/hledger.m4.md | 123 ++++++++++++++++++++++-------------------- 1 file changed, 64 insertions(+), 59 deletions(-) diff --git a/hledger/hledger.m4.md b/hledger/hledger.m4.md index 3f17005dc..36629f2aa 100644 --- a/hledger/hledger.m4.md +++ b/hledger/hledger.m4.md @@ -664,9 +664,8 @@ This option can repeated to set the display style for multiple commodities/currencies. Its argument is as described in the [commodity directive](#commodity-directive). -hledger will occasionally make some additional adjustments to number formatting, -eg adding a trailing decimal mark to disambiguate numbers with digit group marks; -for details, see [Amount formatting, parseability](#amount-formatting-parseability). +In some cases hledger will adjust number formatting to improve their parseability +(such as adding [trailing decimal marks](#trailing-decimal-marks) when needed). ## Colour @@ -1228,7 +1227,7 @@ Or you can declare it per commodity with [`commodity`](#commodity-directive) dir hledger also accepts numbers like `10.` with no digits after the decimal mark (and will sometimes display numbers that way to disambiguate them - see -[Amount formatting, parseability](#amount-formatting-parseability)). +[Trailing decimal marks](#trailing-decimal-marks)). ### Digit group marks @@ -1275,58 +1274,8 @@ output; you can't write them directly in the journal file. - - -### Commodity display style - -For the amounts in each commodity, hledger chooses a consistent display style -(symbol placement, decimal mark and digit group marks, number of decimal digits) -to use in most reports. This is inferred as follows: - -First, if there's a [`D` directive](#d-directive) declaring a default commodity, -that commodity symbol and amount format is applied to all no-symbol amounts in the journal. - -Then each commodity's display style is determined from its -[`commodity` directive](#commodity-directive). We recommend always -declaring commodities with `commodity` directives, since they help -ensure consistent display styles and precisions, and bring other -benefits such as error checking for commodity symbols. -Here's an example: - -```journal -# Set display styles (and decimal marks, for parsing, if there is no decimal-mark directive) -# for the $, EUR, INR and no-symbol commodities: -commodity $1,000.00 -commodity EUR 1.000,00 -commodity INR 9,99,99,999.00 -commodity 1 000 000.9455 -``` - -But for convenience, if a `commodity` directive is not present, -hledger infers a commodity's display styles from its amounts as they are written in the journal -(excluding cost amounts and amounts in periodic transaction rules or auto posting rules). -It uses - -- the symbol placement and decimal mark of the first amount seen -- the digit group marks of the first amount with digit group marks -- and the maximum number of decimal digits seen across all amounts. - -And as fallback if no applicable amounts are found, it would use a -default style, like `$1000.00` (symbol on the left with no space, -period as decimal mark, and two decimal digits). - -Finally, commodity styles can be [overridden](#commodity-styles) by -the `-c/--commodity-style` command line option. - -### Rounding - -Amounts are stored internally as decimal numbers with up to 255 decimal places. -They are displayed -with their original journal precisions by print and print-like reports, -and rounded to their display precision (the number of decimal digits specified by the commodity display style) -by other reports. -When rounding, hledger uses [banker's rounding](https://en.wikipedia.org/wiki/Bankers_rounding) -(it rounds to the nearest even digit). So eg 0.5 displayed with zero decimal digits appears as "0". +By default, the format of amounts in the journal influences how hledger displays them in output. +This is explained in [Commodity display style](#commodity-display-style) below. @@ -4521,14 +4470,68 @@ per:admin .... # PART 3: REPORTING CONCEPTS +# Amount formatting -# Amount formatting, parseability + + +## Commodity display style + +For the amounts in each commodity, hledger chooses a consistent display style +(symbol placement, decimal mark and digit group marks, number of decimal digits) +to use in most reports. This is inferred as follows: + +First, if there's a [`D` directive](#d-directive) declaring a default commodity, +that commodity symbol and amount format is applied to all no-symbol amounts in the journal. + +Then each commodity's display style is determined from its +[`commodity` directive](#commodity-directive). We recommend always +declaring commodities with `commodity` directives, since they help +ensure consistent display styles and precisions, and bring other +benefits such as error checking for commodity symbols. +Here's an example: + +```journal +# Set display styles (and decimal marks, for parsing, if there is no decimal-mark directive) +# for the $, EUR, INR and no-symbol commodities: +commodity $1,000.00 +commodity EUR 1.000,00 +commodity INR 9,99,99,999.00 +commodity 1 000 000.9455 +``` + +But for convenience, if a `commodity` directive is not present, +hledger infers a commodity's display styles from its amounts as they are written in the journal +(excluding cost amounts and amounts in periodic transaction rules or auto posting rules). +It uses + +- the symbol placement and decimal mark of the first amount seen +- the digit group marks of the first amount with digit group marks +- and the maximum number of decimal digits seen across all amounts. + +And as fallback if no applicable amounts are found, it would use a +default style, like `$1000.00` (symbol on the left with no space, +period as decimal mark, and two decimal digits). + +Finally, commodity styles can be [overridden](#commodity-styles) by +the `-c/--commodity-style` command line option. + +## Rounding + +Amounts are stored internally as decimal numbers with up to 255 decimal places. +They are displayed +with their original journal precisions by print and print-like reports, +and rounded to their display precision (the number of decimal digits specified by the commodity display style) +by other reports. +When rounding, hledger uses [banker's rounding](https://en.wikipedia.org/wiki/Bankers_rounding) +(it rounds to the nearest even digit). So eg 0.5 displayed with zero decimal digits appears as "0". + +## Trailing decimal marks If you're wondering why your [`print`](#print) report sometimes shows trailing decimal marks, with no decimal digits; it does this when showing amounts that have digit group marks but no decimal digits, to disambiguate them and allow them to be re-parsed reliably -(see also [Decimal marks](#decimal-marks). +(see [Decimal marks](#decimal-marks)). Eg: ```journal @@ -4565,7 +4568,9 @@ $ hledger print -c '$1,000.00' --round=soft ``` -More generally: hledger output falls into three rough categories, which +## Amount parseability + +More generally, hledger output falls into three rough categories, which format amounts a little bit differently to suit different consumers: **1. "hledger-readable output" - should be readable by hledger (and by humans)** From 158e0850fda57f9e95c85aea4586a9c6737ea6a5 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Thu, 29 Feb 2024 16:56:22 -1000 Subject: [PATCH 14/41] ;doc:journal:directives: fix formatting --- hledger/hledger.m4.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/hledger/hledger.m4.md b/hledger/hledger.m4.md index 36629f2aa..b00d110de 100644 --- a/hledger/hledger.m4.md +++ b/hledger/hledger.m4.md @@ -1744,12 +1744,11 @@ Here are all hledger's directives, with their effects and scope summarised - nin | **[`account`]** | Declares an account, for [checking](#check) all entries in all files;
and its [display order](#account-display-order) and [type](#declaring-account-types).
Subdirectives: any text, ignored. | N | | **[`alias`]** | Rewrites account names, in following entries until end of current file or [`end aliases`].
Command line equivalent: [`--alias`] | Y | | **[`comment`]** | Ignores part of the journal file, until end of current file or `end comment`. | Y | -| **[`commodity`]** | Declares up to four things: -
1. a commodity symbol, for checking all amounts in all files
2. the display style for all amounts of this commodity
3. the decimal mark for parsing amounts of this commodity, in the rest of this file and its children, if there is no `decimal-mark` directive
4. the precision to use for balanced-transaction checking in this commodity, in this file and its children.
Takes precedence over `D`.
Subdirectives: `format` (ignored).
Command line equivalent: [`-c/--commodity-style`](#commodity-styles) | N,
N,
Y,
Y | +| **[`commodity`]** | Declares up to four things:
1. a commodity symbol, for checking all amounts in all files
2. the display style for all amounts of this commodity
3. the decimal mark for parsing amounts of this commodity, in the rest of this file and its children, if there is no `decimal-mark` directive
4. the precision to use for balanced-transaction checking in this commodity, in this file and its children.
Takes precedence over `D`.
Subdirectives: `format` (ignored).
Command line equivalent: [`-c/--commodity-style`](#commodity-styles) | N,
N,
Y,
Y | | **[`decimal-mark`]** | Declares the decimal mark, for parsing amounts of all commodities in following entries until next `decimal-mark` or end of current file. Included files can override. Takes precedence over `commodity` and `D`. | Y | | **[`include`]** | Includes entries and directives from another file, as if they were written inline.
Command line alternative: multiple [`-f/--file`](#multiple-files) | N | | **[`payee`]** | Declares a payee name, for checking all entries in all files. | N | -| **[`P`]** | Declares the market price of a commodity on some date, for [value reports](#value-reporting). | N | +| **[`P`]** | Declares the market price of a commodity on some date, for [value reports](#value-reporting). | N | | **[`~`]** (tilde) | Declares a periodic transaction rule that generates future transactions with `--forecast` and budget goals with `balance --budget`. | N | | Other syntax: | | | | **[`apply account`]** | Prepends a common parent account to all account names, in following entries until end of current file or `end apply account`. | Y | From 1a7523d16e06bf5b2edf711d1ba688fa72984146 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Thu, 29 Feb 2024 17:09:09 -1000 Subject: [PATCH 15/41] ;doc:journal: move complex discussion of other lot notations later --- hledger/hledger.m4.md | 122 +++++++++++++++++++++--------------------- 1 file changed, 61 insertions(+), 61 deletions(-) diff --git a/hledger/hledger.m4.md b/hledger/hledger.m4.md index b00d110de..556e376b4 100644 --- a/hledger/hledger.m4.md +++ b/hledger/hledger.m4.md @@ -1332,67 +1332,6 @@ Note that the cost normally should be a positive amount, though it's not require This can be a little confusing, see discussion at [--infer-market-prices: market prices from transactions](#--infer-market-prices-market-prices-from-transactions). -### Other cost/lot notations - -A slight digression for Ledger and Beancount users. Ledger has a number of cost/lot-related notations: - -- `@ UNITCOST` and `@@ TOTALCOST` - - expresses a conversion rate, as in hledger - - when buying, also creates a lot than can be selected at selling time - -- `(@) UNITCOST` and `(@@) TOTALCOST` ([virtual cost][ledger: virtual posting costs]) - - like the above, but also means "this cost was exceptional, don't use it when inferring market prices". - -Currently, hledger treats the above like `@` and `@@`; the parentheses are ignored. - -- `{=FIXEDUNITCOST}` and `{{{{=FIXEDTOTALCOST}}}}` ([fixed price][ledger: fixing lot prices]) - - when buying, means "this cost is also the fixed price, don't let it fluctuate in value reports" - -- `{UNITCOST}` and `{{{{TOTALCOST}}}}` ([lot price][ledger: buying and selling stock]) - - can be used identically to `@ UNITCOST` and `@@ TOTALCOST`, also creates a lot - - when selling, combined with `@ ...`, specifies an investment lot by its cost basis; does not check if that lot is present - -- and related: `[YYYY/MM/DD]` ([lot date][ledger: lot dates]) - - when buying, attaches this acquisition date to the lot - - when selling, selects a lot by its acquisition date - -- `(SOME TEXT)` ([lot note][ledger: lot notes]) - - when buying, attaches this note to the lot - - when selling, selects a lot by its note - -Currently, hledger accepts any or all of the above in any order after the posting amount, but ignores them. -(This can break transaction balancing.) - -[ledger: virtual posting costs]: https://www.ledger-cli.org/3.0/doc/ledger3.html#Virtual-posting-costs -[ledger: buying and selling stock]: https://www.ledger-cli.org/3.0/doc/ledger3.html#Buying-and-Selling-Stock -[ledger: fixing lot prices]: https://www.ledger-cli.org/3.0/doc/ledger3.html#Fixing-Lot-Prices -[ledger: lot dates]: https://www.ledger-cli.org/3.0/doc/ledger3.html#Lot-dates -[ledger: lot notes]: https://www.ledger-cli.org/3.0/doc/ledger3.html#Lot-notes - -For Beancount users, the [notation][beancount: costs and prices] and [behaviour][beancount: how inventories work] is different: - -- `@ UNITCOST` and `@@ TOTALCOST` - - expresses a cost without creating a lot, as in hledger - - when buying (augmenting) or selling (reducing) a lot, combined with `{...}`: documents the cost/selling price (not used for transaction balancing) - -- `{UNITCOST}` and `{{{{TOTALCOST}}}}` - - when buying (augmenting), expresses the cost for transaction balancing, and also creates a lot with this cost basis attached - - when selling (reducing), - - selects a lot by its cost basis - - raises an error if that lot is not present or can not be selected unambiguously (depending on booking method configured) - - expresses the selling price for transaction balancing - -Currently, hledger accepts the `{UNITCOST}`/`{{{{TOTALCOST}}}}` notation but ignores it. - -- variations: `{}`, `{YYYY-MM-DD}`, `{"LABEL"}`, `{UNITCOST, "LABEL"}`, `{UNITCOST, YYYY-MM-DD, "LABEL"}` etc. - -Currently, hledger rejects these. - - -[beancount: costs and prices]: https://beancount.github.io/docs/beancount_language_syntax.html#costs-and-prices -[beancount: how inventories work]: https://beancount.github.io/docs/how_inventories_work.html - - ## Balance assertions hledger supports @@ -2832,6 +2771,67 @@ value EXPR See also for a detailed hledger/Ledger syntax comparison. +### Other cost/lot notations + +A slight digression for Ledger and Beancount users. Ledger has a number of cost/lot-related notations: + +- `@ UNITCOST` and `@@ TOTALCOST` + - expresses a conversion rate, as in hledger + - when buying, also creates a lot than can be selected at selling time + +- `(@) UNITCOST` and `(@@) TOTALCOST` ([virtual cost][ledger: virtual posting costs]) + - like the above, but also means "this cost was exceptional, don't use it when inferring market prices". + +Currently, hledger treats the above like `@` and `@@`; the parentheses are ignored. + +- `{=FIXEDUNITCOST}` and `{{{{=FIXEDTOTALCOST}}}}` ([fixed price][ledger: fixing lot prices]) + - when buying, means "this cost is also the fixed price, don't let it fluctuate in value reports" + +- `{UNITCOST}` and `{{{{TOTALCOST}}}}` ([lot price][ledger: buying and selling stock]) + - can be used identically to `@ UNITCOST` and `@@ TOTALCOST`, also creates a lot + - when selling, combined with `@ ...`, specifies an investment lot by its cost basis; does not check if that lot is present + +- and related: `[YYYY/MM/DD]` ([lot date][ledger: lot dates]) + - when buying, attaches this acquisition date to the lot + - when selling, selects a lot by its acquisition date + +- `(SOME TEXT)` ([lot note][ledger: lot notes]) + - when buying, attaches this note to the lot + - when selling, selects a lot by its note + +Currently, hledger accepts any or all of the above in any order after the posting amount, but ignores them. +(This can break transaction balancing.) + +[ledger: virtual posting costs]: https://www.ledger-cli.org/3.0/doc/ledger3.html#Virtual-posting-costs +[ledger: buying and selling stock]: https://www.ledger-cli.org/3.0/doc/ledger3.html#Buying-and-Selling-Stock +[ledger: fixing lot prices]: https://www.ledger-cli.org/3.0/doc/ledger3.html#Fixing-Lot-Prices +[ledger: lot dates]: https://www.ledger-cli.org/3.0/doc/ledger3.html#Lot-dates +[ledger: lot notes]: https://www.ledger-cli.org/3.0/doc/ledger3.html#Lot-notes + +For Beancount users, the [notation][beancount: costs and prices] and [behaviour][beancount: how inventories work] is different: + +- `@ UNITCOST` and `@@ TOTALCOST` + - expresses a cost without creating a lot, as in hledger + - when buying (augmenting) or selling (reducing) a lot, combined with `{...}`: documents the cost/selling price (not used for transaction balancing) + +- `{UNITCOST}` and `{{{{TOTALCOST}}}}` + - when buying (augmenting), expresses the cost for transaction balancing, and also creates a lot with this cost basis attached + - when selling (reducing), + - selects a lot by its cost basis + - raises an error if that lot is not present or can not be selected unambiguously (depending on booking method configured) + - expresses the selling price for transaction balancing + +Currently, hledger accepts the `{UNITCOST}`/`{{{{TOTALCOST}}}}` notation but ignores it. + +- variations: `{}`, `{YYYY-MM-DD}`, `{"LABEL"}`, `{UNITCOST, "LABEL"}`, `{UNITCOST, YYYY-MM-DD, "LABEL"}` etc. + +Currently, hledger rejects these. + + +[beancount: costs and prices]: https://beancount.github.io/docs/beancount_language_syntax.html#costs-and-prices +[beancount: how inventories work]: https://beancount.github.io/docs/how_inventories_work.html + + # CSV From 24571f99e0ce8a9ac5e57c0b8435d8ca9b1e92c3 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Thu, 29 Feb 2024 17:48:22 -1000 Subject: [PATCH 16/41] ;doc:journal: drop redundant/wrong Querying with cost or value section --- hledger/hledger.m4.md | 25 +++++++++---------------- 1 file changed, 9 insertions(+), 16 deletions(-) diff --git a/hledger/hledger.m4.md b/hledger/hledger.m4.md index 556e376b4..8a42d8a30 100644 --- a/hledger/hledger.m4.md +++ b/hledger/hledger.m4.md @@ -5041,6 +5041,8 @@ This allows one to combine queries using `AND`, `OR`, and `NOT`. `expr:"expenses:food OR (tag:A expenses:drink)"` +(But `OR` may not be reliable currently, [#2177](https://github.com/simonmichael/hledger/issues/2177).) + ## Queries and command options Some queries can also be expressed as command-line options: @@ -5049,25 +5051,16 @@ Some queries can also be expressed as command-line options: When you mix command options and query arguments, generally the resulting query is their intersection. +## Queries and account aliases + +When account names are [rewritten](#alias-directive) with `--alias` or `alias`, +`acct:` will match either the old or the new account name. + ## Queries and valuation When amounts are converted to other commodities in [cost](#cost-reporting) or [value](#value-reporting) reports, -`cur:` and `amt:` match the old commodity symbol and the old amount quantity, -not the new ones -(except in hledger 1.22.0 where it's reversed, see [#1625](https://github.com/simonmichael/hledger/issues/1625)). - -## Querying with account aliases - -When account names are [rewritten](#alias-directive) with `--alias` or `alias`, -note that `acct:` will match either the old or the new account name. - -## Querying with cost or value - -When amounts are converted to other commodities in [cost](#cost-reporting) or [value](#value-reporting) reports, -note that `cur:` matches the new commodity symbol, and not the old one, -and `amt:` matches the new quantity, and not the old one. -Note: this changed in hledger 1.22, previously it was the reverse, -see the discussion at [#1625](https://github.com/simonmichael/hledger/issues/1625). +`cur:` and `amt:` match the old commodity symbol and the old amount quantity, not the new ones. +(Except in hledger 1.22, [#1625](https://github.com/simonmichael/hledger/issues/1625).) # Pivoting From 39a0a4d08aa16ac36e0b3a31e2a3343f6af55dd9 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Thu, 29 Feb 2024 18:00:10 -1000 Subject: [PATCH 17/41] ;doc:journal:valuation: cleanups --- hledger/hledger.m4.md | 124 +++++++++++++++++++++--------------------- 1 file changed, 61 insertions(+), 63 deletions(-) diff --git a/hledger/hledger.m4.md b/hledger/hledger.m4.md index 8a42d8a30..c214feea4 100644 --- a/hledger/hledger.m4.md +++ b/hledger/hledger.m4.md @@ -5687,38 +5687,6 @@ This means: Amounts for which no valuation commodity can be found are not converted. -## Simple valuation examples - -Here are some quick examples of `-V`: - -```journal -; 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 ? -```cli -$ hledger -f t.j bal -N euros - €100 assets:euros -``` -What are they worth at end of nov 3 ? -```cli -$ hledger -f t.j bal -N euros -V -e 2016/11/4 - $110.00 assets:euros -``` -What are they worth after 2016/12/21 ? (no report end date specified, defaults to today) -```cli -$ hledger -f t.j bal -N euros -V - $103.00 assets:euros -``` - ## --value: Flexible valuation `-V` and `-X` are special cases of the more general `--value` option: @@ -5755,7 +5723,38 @@ a comma, then the target commodity's symbol. Eg: **`--value=now,EUR`**. hledger will do its best to convert amounts to this commodity, deducing [market prices](#p-directive) as described above. -## More valuation examples +## Valuation examples + +Here are some quick examples of `-V`: + +```journal +; 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 ? +```cli +$ hledger -f t.j bal -N euros + €100 assets:euros +``` +What are they worth at end of nov 3 ? +```cli +$ hledger -f t.j bal -N euros -V -e 2016/11/4 + $110.00 assets:euros +``` +What are they worth after 2016/12/21 ? (no report end date specified, defaults to today) +```cli +$ hledger -f t.j bal -N euros -V + $103.00 assets:euros +``` + Here are some examples showing the effect of `--value`, as seen with `print`: @@ -5844,8 +5843,7 @@ $ hledger -f- print --value=2000-01-15 ## Interaction of valuation and queries -When matching postings based on queries in the presence of valuation, the -following happens. +When matching postings based on queries in the presence of valuation, the following happens: 1. The query is separated into two parts: 1. the currency (`cur:`) or amount (`amt:`). @@ -5854,20 +5852,44 @@ following happens. 3. Valuation is applied to the postings. 4. The postings are matched to the other parts of the query based on post-valued amounts. -See: -[1625](https://github.com/simonmichael/hledger/issues/1625) +Related: +[#1625](https://github.com/simonmichael/hledger/issues/1625) ## Effect of valuation on reports -Here is a reference for how valuation is supposed to affect each part of hledger's reports (and a glossary). -(It's wide, you'll have to scroll sideways.) +Here is a reference for how valuation is supposed to affect each part of hledger's reports. +(It's wide, you may need to scroll sideways.) It may be useful when troubleshooting. If you find problems, please report them, ideally with a reproducible example. Related: [#329](https://github.com/simonmichael/hledger/issues/329), [#1083](https://github.com/simonmichael/hledger/issues/1083). +First, a quick glossary: + +*cost* +: calculated using price(s) recorded in the transaction(s). + +*value* +: market value using available market price declarations, or the unchanged amount if no conversion rate can be found. + +*report start* +: the first day of the report period specified with -b or -p or date:, otherwise today. + +*report or journal start* +: the first day of the report period specified with -b or -p or date:, otherwise the earliest transaction date in the journal, otherwise today. + +*report end* +: the last day of the report period specified with -e or -p or date:, otherwise today. + +*report or journal end* +: the last day of the report period specified with -e or -p or date:, otherwise the latest transaction date in the journal, otherwise today. + +*report interval* +: a flag (-D/-W/-M/-Q/-Y) or period expression that activates the report's multi-period mode (whether showing one or many subperiods). + + | Report type | `-B`, `--cost` | `-V`, `-X` | `--value=then` | `--value=end` | `--value=DATE`, `--value=now` | |-----------------------------------------------------|------------------------------------------------------------------|-------------------------------------------------------------------|------------------------------------------------------------------------------------------------|-------------------------------------------------------------------|-----------------------------------------| | **print** | | | | | | @@ -5898,30 +5920,6 @@ Related: `--cumulative` is omitted to save space, it works like `-H` but with a zero starting balance. -**Glossary:** - -*cost* -: calculated using price(s) recorded in the transaction(s). - -*value* -: market value using available market price declarations, or the unchanged amount if no conversion rate can be found. - -*report start* -: the first day of the report period specified with -b or -p or date:, otherwise today. - -*report or journal start* -: the first day of the report period specified with -b or -p or date:, otherwise the earliest transaction date in the journal, otherwise today. - -*report end* -: the last day of the report period specified with -e or -p or date:, otherwise today. - -*report or journal end* -: the last day of the report period specified with -e or -p or date:, otherwise the latest transaction date in the journal, otherwise today. - -*report interval* -: a flag (-D/-W/-M/-Q/-Y) or period expression that activates the report's multi-period mode (whether showing one or many subperiods). - - # PART 4: COMMANDS ## Commands overview From 3e93b69c251ad866756e1ba6403469cc1ec9e24c Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Thu, 29 Feb 2024 18:14:52 -1000 Subject: [PATCH 18/41] ;doc:balance: consolidated --related/-r doc --- hledger/Hledger/Cli/Commands/Balance.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/hledger/Hledger/Cli/Commands/Balance.md b/hledger/Hledger/Cli/Commands/Balance.md index cd3b5f106..17df1cab4 100644 --- a/hledger/Hledger/Cli/Commands/Balance.md +++ b/hledger/Hledger/Cli/Commands/Balance.md @@ -39,6 +39,7 @@ Many of these work with the higher-level commands as well. - or value of balance changes ([`-V`](#valuation-type)) - or change of balance values ([`--valuechange`](#balance-report-types)) - or unrealised capital gain/loss ([`--gain`](#balance-report-types)) +- or balance changes from sibling postings (`--related`/`-r`) - or postings count ([`--count`](#balance-report-types)) ..in.. @@ -77,9 +78,6 @@ This command supports the with output formats `txt`, `csv`, `tsv` (*Added in 1.32*), `json`, and (multi-period reports only:) `html`. In `txt` output in a colour-supporting terminal, negative amounts are shown in red. -The `--related`/`-r` flag shows the balance of the *other* postings in the -transactions of the postings which would normally be shown. - ### Simple balance report With no arguments, `balance` shows a list of all accounts and their @@ -189,6 +187,7 @@ Some example formats: [valuation]: #valuation [valuation date(s)]: #valuation-date [valuation commodity]: #valuation-commodity + ### Filtered balance report You can show fewer accounts, a different time period, totals from From babaf709328c0414cffd9a3d12bdc7eb851ad66d Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Thu, 29 Feb 2024 19:09:39 -1000 Subject: [PATCH 19/41] ;doc:journal:transaction balancing, commodity directive: highlight #2135 --- hledger/hledger.m4.md | 17 +++++++++++++++-- 1 file changed, 15 insertions(+), 2 deletions(-) diff --git a/hledger/hledger.m4.md b/hledger/hledger.m4.md index c214feea4..09d62567a 100644 --- a/hledger/hledger.m4.md +++ b/hledger/hledger.m4.md @@ -1527,7 +1527,7 @@ which are difficult or inconvenient to handle on a computer. So to be a practical accounting system, hledger allows some imprecision when checking transaction balancedness. The question is, how much imprecision should be allowed ? -hledger currently decides it based on the commodity display precisions inferred or declared for each commodity: +hledger currently decides it based on the [commodity display styles](#commodity-display-style)(\*): if the postings' sum would appear to be zero when displayed with the standard display precisions, the transaction is considered balanced. Or equivalently: if the journal entry is displayed with amounts rounded to the @@ -1543,6 +1543,12 @@ you might need to fix some of your journal entries (ie, add decimal digits to ma Other PTA tools (Ledger, Beancount..) have their own ways of doing it. Possible improvements are discussed at [#1964](https://github.com/simonmichael/hledger/issues/1964). +(\*) (If you have multiple journal files, watch out for this snag: +`commodity` directives should be placed where they influence all files, eg in a topmost parent file. +Related: +[`commodity` directive](#commodity-directive), +[#2135](https://github.com/simonmichael/hledger/issues/2135)) + ## Tags @@ -2108,7 +2114,14 @@ The `commodity` directive performs several functions: Declaring commodities solves several common parsing/display problems, so we recommend it. -(Related dev discussion: [#793](https://github.com/simonmichael/hledger/issues/793).) +Note that effects 3 and 4 above end at the end of the directive's file, +and will not affect sibling or parent files. +So if you are relying on them (especially 4) and using multiple files, +consider placing your commodity directives in a top-level parent file, +where they can influence all the included files. +(Though I keep mine in a `YYYY-commodities` child file without trouble.) + +(Related: [#793](https://github.com/simonmichael/hledger/issues/793)) ### Commodity directive syntax From 67f027de331b2acad572c0af8c76a6ee90f99485 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Thu, 29 Feb 2024 19:23:31 -1000 Subject: [PATCH 20/41] ;doc:journal:transaction balancing, commodity directive: simplify --- hledger/hledger.m4.md | 14 +++++--------- 1 file changed, 5 insertions(+), 9 deletions(-) diff --git a/hledger/hledger.m4.md b/hledger/hledger.m4.md index 09d62567a..dcf6b0602 100644 --- a/hledger/hledger.m4.md +++ b/hledger/hledger.m4.md @@ -1527,7 +1527,7 @@ which are difficult or inconvenient to handle on a computer. So to be a practical accounting system, hledger allows some imprecision when checking transaction balancedness. The question is, how much imprecision should be allowed ? -hledger currently decides it based on the [commodity display styles](#commodity-display-style)(\*): +hledger currently decides it based on the [commodity display styles](#commodity-display-style): if the postings' sum would appear to be zero when displayed with the standard display precisions, the transaction is considered balanced. Or equivalently: if the journal entry is displayed with amounts rounded to the @@ -1543,11 +1543,8 @@ you might need to fix some of your journal entries (ie, add decimal digits to ma Other PTA tools (Ledger, Beancount..) have their own ways of doing it. Possible improvements are discussed at [#1964](https://github.com/simonmichael/hledger/issues/1964). -(\*) (If you have multiple journal files, watch out for this snag: -`commodity` directives should be placed where they influence all files, eg in a topmost parent file. -Related: -[`commodity` directive](#commodity-directive), -[#2135](https://github.com/simonmichael/hledger/issues/2135)) +Note: if you have multiple journal files, and are relying on commodity directives to make imprecise journal entries balance, +the directives' placement might be important - see [`commodity` directive](#commodity-directive). ## Tags @@ -2117,9 +2114,8 @@ Declaring commodities solves several common parsing/display problems, so we reco Note that effects 3 and 4 above end at the end of the directive's file, and will not affect sibling or parent files. So if you are relying on them (especially 4) and using multiple files, -consider placing your commodity directives in a top-level parent file, -where they can influence all the included files. -(Though I keep mine in a `YYYY-commodities` child file without trouble.) +placing your commodity directives in a top-level parent file might be important. +Or, keep your decimal marks unambiguous and your entries well balanced and precise. (Related: [#793](https://github.com/simonmichael/hledger/issues/793)) From d8f86a9b7dd2c867ef72ba21cd1979ee1cdb0b24 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Thu, 29 Feb 2024 22:56:23 -1000 Subject: [PATCH 21/41] ;doc:balance: updates, cleanups --- hledger/Hledger/Cli/Commands/Balance.md | 38 +++++++++---------------- 1 file changed, 13 insertions(+), 25 deletions(-) diff --git a/hledger/Hledger/Cli/Commands/Balance.md b/hledger/Hledger/Cli/Commands/Balance.md index 17df1cab4..2ca9ef987 100644 --- a/hledger/Hledger/Cli/Commands/Balance.md +++ b/hledger/Hledger/Cli/Commands/Balance.md @@ -370,7 +370,9 @@ Multi-period reports with many periods can be too wide for easy viewing in the t Here are some ways to handle that: - Hide the totals row with `-N/--no-total` -- Convert to a single currency with `-V` +- Filter to a single currency with `cur:` +- Convert to a single currency with `-V [--infer-market-price]` +- Use a more compact layout like `--layout=bare` - Maximize the terminal window - Reduce the terminal's font size - View with a pager like less, eg: `hledger bal -D --color=yes | less -RS` @@ -439,13 +441,13 @@ It is one of: #### Accumulation type -How amounts should accumulate across report periods. +How amounts should accumulate across a report's subperiods/columns. Another way to say it: which time period's postings should contribute to each cell's calculation. It is one of: - `--change` : calculate with postings from column start to column end, ie "just this column". Typically used to see revenues/expenses. - (**default for balance, incomestatement**) + (**default for balance, cashflow, incomestatement**) - `--cumulative` : calculate with postings from report start to column end, ie "previous columns plus this column". Typically used to show changes accumulated since the report's start date. @@ -454,7 +456,7 @@ It is one of: - `--historical/-H` : calculate with postings from journal start to column end, ie "all postings from before report start date until this column's end". Typically used to see historical end balances of assets/liabilities/equity. - (**default for balancesheet, balancesheetequity, cashflow**) + (**default for balancesheet, balancesheetequity**) #### Valuation type @@ -657,30 +659,16 @@ and then select from multiple budgets defined in your journal. #### Budgeting vs forecasting -`--budget` and `--forecast` both use the periodic transaction rules in the journal to generate temporary transactions for reporting purposes. +`--forecast` and `--budget` both use the periodic transaction rules in the journal to generate temporary transactions for reporting purposes. However they are separate features - though you can use both at the same time if you want. Here are some differences between them: -1. `--budget` is a command-specific option; it selects the **budget report**. - - `--forecast` is a general option; **forecasting works with all reports**. - -2. `--budget` uses **all periodic rules**; `--budget=DESCPAT` uses **just the rules matched** by DESCPAT. - - `--forecast` uses **all periodic rules**. - -3. `--budget`'s budget goal transactions are invisible, except that they produce **goal amounts**. - - `--forecast`'s forecast transactions are visible, and **appear in reports**. - -4. `--budget` generates budget goal transactions **throughout the report period**, - optionally restricted by periods specified in the periodic transaction rules. - - `--forecast` generates forecast transactions - from **after the last regular transaction**, to the end of the report period; - while `--forecast=PERIODEXPR` generates them **throughout the specified period**; - both optionally restricted by periods specified in the periodic transaction rules. - +| --forecast | --budget | +|------------|----------| +| is a general option; it enables forecasting with all reports | is a balance command option; it selects the balance report's budget mode | +| generates visible transactions which appear in reports | generates invisible transactions which produce goal amounts | +| generates forecast transactions from after the last regular transaction, to the end of the report period; or with an argument `--forecast=PERIODEXPR` generates them throughout the specified period, both optionally restricted by periods specified in the periodic transaction rules | generates budget goal transactions throughout the report period, optionally restricted by periods specified in the periodic transaction rules | +| uses all periodic rules | uses all periodic rules; or with an argument `--budget=DESCPAT` uses just the rules matched by DESCPAT | ### Balance report layout From 7e28e38bbc7756c1db6206cb22a02594d0347e87 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Thu, 29 Feb 2024 23:13:23 -1000 Subject: [PATCH 22/41] ;doc:balance: cleanups --- hledger/Hledger/Cli/Commands/Balance.md | 219 ++++++++++++------------ 1 file changed, 111 insertions(+), 108 deletions(-) diff --git a/hledger/Hledger/Cli/Commands/Balance.md b/hledger/Hledger/Cli/Commands/Balance.md index 2ca9ef987..5901f6d47 100644 --- a/hledger/Hledger/Cli/Commands/Balance.md +++ b/hledger/Hledger/Cli/Commands/Balance.md @@ -682,8 +682,8 @@ It has four possible values: - `--layout=bare`: commodity symbols are in their own column, amounts are bare numbers - `--layout=tidy`: data is normalised to easily-consumed "tidy" form, with one row per data value -Here are the `--layout` modes supported by each [output format](#output-format); -note only CSV output supports all of them: +Here are the `--layout` modes supported by each [output format](#output-format) +Only CSV output supports all of them: | - | txt | csv | html | json | sql | |------|-----|-----|------|------|-----| @@ -694,119 +694,122 @@ note only CSV output supports all of them: Examples: -- Wide layout. With many commodities, reports can be very wide: - ```cli - $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide - Balance changes in 2012-01-01..2014-12-31: - - || 2012 2013 2014 Total - ==================++==================================================================================================================================================================================================================== - Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT 70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT 70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT - ------------------++-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- - || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT 70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT 70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT - ``` +#### Wide layout +With many commodities, reports can be very wide: +```cli +$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide +Balance changes in 2012-01-01..2014-12-31: -- Limited wide layout. A width limit reduces the width, but some commodities will be hidden: - ```cli - $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide,32 - Balance changes in 2012-01-01..2014-12-31: - - || 2012 2013 2014 Total - ==================++=========================================================================================================================== - Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. -11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more.. - ------------------++--------------------------------------------------------------------------------------------------------------------------- - || 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. -11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more.. - ``` + || 2012 2013 2014 Total +==================++==================================================================================================================================================================================================================== + Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT 70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT 70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT +------------------++-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- + || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT 70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT 70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT +``` -- Tall layout. Each commodity gets a new line (may be different in each column), and account names are repeated: - ```cli - $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=tall - Balance changes in 2012-01-01..2014-12-31: - - || 2012 2013 2014 Total - ==================++================================================== - Assets:US:ETrade || 10.00 ITOT 70.00 GLD -11.00 ITOT 70.00 GLD - Assets:US:ETrade || 337.18 USD 18.00 ITOT 4881.44 USD 17.00 ITOT - Assets:US:ETrade || 12.00 VEA -98.12 USD 14.00 VEA 5120.50 USD - Assets:US:ETrade || 106.00 VHT 10.00 VEA 170.00 VHT 36.00 VEA - Assets:US:ETrade || 18.00 VHT 294.00 VHT - ------------------++-------------------------------------------------- - || 10.00 ITOT 70.00 GLD -11.00 ITOT 70.00 GLD - || 337.18 USD 18.00 ITOT 4881.44 USD 17.00 ITOT - || 12.00 VEA -98.12 USD 14.00 VEA 5120.50 USD - || 106.00 VHT 10.00 VEA 170.00 VHT 36.00 VEA - || 18.00 VHT 294.00 VHT - ``` +A width limit reduces the width, but some commodities will be hidden: +```cli +$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide,32 +Balance changes in 2012-01-01..2014-12-31: -- Bare layout. Commodity symbols are kept in one column, each commodity gets its own report row, account names are repeated: - ```cli - $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=bare - Balance changes in 2012-01-01..2014-12-31: - - || Commodity 2012 2013 2014 Total - ==================++============================================= - Assets:US:ETrade || GLD 0 70.00 0 70.00 - Assets:US:ETrade || ITOT 10.00 18.00 -11.00 17.00 - Assets:US:ETrade || USD 337.18 -98.12 4881.44 5120.50 - Assets:US:ETrade || VEA 12.00 10.00 14.00 36.00 - Assets:US:ETrade || VHT 106.00 18.00 170.00 294.00 - ------------------++--------------------------------------------- - || GLD 0 70.00 0 70.00 - || ITOT 10.00 18.00 -11.00 17.00 - || USD 337.18 -98.12 4881.44 5120.50 - || VEA 12.00 10.00 14.00 36.00 - || VHT 106.00 18.00 170.00 294.00 - ``` + || 2012 2013 2014 Total +==================++=========================================================================================================================== + Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. -11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more.. +------------------++--------------------------------------------------------------------------------------------------------------------------- + || 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. -11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more.. +``` -- Bare layout also affects [CSV output](#output-format), - which is useful for producing data that is easier to consume, eg for making charts: - ```cli - $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -O csv --layout=bare - "account","commodity","balance" - "Assets:US:ETrade","GLD","70.00" - "Assets:US:ETrade","ITOT","17.00" - "Assets:US:ETrade","USD","5120.50" - "Assets:US:ETrade","VEA","36.00" - "Assets:US:ETrade","VHT","294.00" - "total","GLD","70.00" - "total","ITOT","17.00" - "total","USD","5120.50" - "total","VEA","36.00" - "total","VHT","294.00" - ``` +#### Tall layout +Each commodity gets a new line (may be different in each column), and account names are repeated: +```cli +$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=tall +Balance changes in 2012-01-01..2014-12-31: -- Note: bare layout will sometimes display an extra row for the no-symbol commodity, - because of zero amounts (hledger treats zeroes as commodity-less, usually). - This can break `hledger-bar` confusingly (workaround: add a `cur:` query to exclude - the no-symbol row). + || 2012 2013 2014 Total +==================++================================================== + Assets:US:ETrade || 10.00 ITOT 70.00 GLD -11.00 ITOT 70.00 GLD + Assets:US:ETrade || 337.18 USD 18.00 ITOT 4881.44 USD 17.00 ITOT + Assets:US:ETrade || 12.00 VEA -98.12 USD 14.00 VEA 5120.50 USD + Assets:US:ETrade || 106.00 VHT 10.00 VEA 170.00 VHT 36.00 VEA + Assets:US:ETrade || 18.00 VHT 294.00 VHT +------------------++-------------------------------------------------- + || 10.00 ITOT 70.00 GLD -11.00 ITOT 70.00 GLD + || 337.18 USD 18.00 ITOT 4881.44 USD 17.00 ITOT + || 12.00 VEA -98.12 USD 14.00 VEA 5120.50 USD + || 106.00 VHT 10.00 VEA 170.00 VHT 36.00 VEA + || 18.00 VHT 294.00 VHT +``` -- Tidy layout produces normalised "tidy data", where every variable - has its own column and each row represents a single data point. - See for more. - This is the easiest kind of data for other software to consume. - Here's how it looks: - - ```cli - $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -Y -O csv --layout=tidy - "account","period","start_date","end_date","commodity","value" - "Assets:US:ETrade","2012","2012-01-01","2012-12-31","GLD","0" - "Assets:US:ETrade","2012","2012-01-01","2012-12-31","ITOT","10.00" - "Assets:US:ETrade","2012","2012-01-01","2012-12-31","USD","337.18" - "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VEA","12.00" - "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VHT","106.00" - "Assets:US:ETrade","2013","2013-01-01","2013-12-31","GLD","70.00" - "Assets:US:ETrade","2013","2013-01-01","2013-12-31","ITOT","18.00" - "Assets:US:ETrade","2013","2013-01-01","2013-12-31","USD","-98.12" - "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VEA","10.00" - "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VHT","18.00" - "Assets:US:ETrade","2014","2014-01-01","2014-12-31","GLD","0" - "Assets:US:ETrade","2014","2014-01-01","2014-12-31","ITOT","-11.00" - "Assets:US:ETrade","2014","2014-01-01","2014-12-31","USD","4881.44" - "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VEA","14.00" - "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VHT","170.00" - ``` +#### Bare layout +Commodity symbols are kept in one column, each commodity has its own row, +amounts are bare numbers, account names are repeated: +```cli +$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=bare +Balance changes in 2012-01-01..2014-12-31: -### Useful balance reports + || Commodity 2012 2013 2014 Total +==================++============================================= + Assets:US:ETrade || GLD 0 70.00 0 70.00 + Assets:US:ETrade || ITOT 10.00 18.00 -11.00 17.00 + Assets:US:ETrade || USD 337.18 -98.12 4881.44 5120.50 + Assets:US:ETrade || VEA 12.00 10.00 14.00 36.00 + Assets:US:ETrade || VHT 106.00 18.00 170.00 294.00 +------------------++--------------------------------------------- + || GLD 0 70.00 0 70.00 + || ITOT 10.00 18.00 -11.00 17.00 + || USD 337.18 -98.12 4881.44 5120.50 + || VEA 12.00 10.00 14.00 36.00 + || VHT 106.00 18.00 170.00 294.00 +``` + +Bare layout also affects [CSV output](#output-format), +which is useful for producing data that is easier to consume, eg for making charts: +```cli +$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -O csv --layout=bare +"account","commodity","balance" +"Assets:US:ETrade","GLD","70.00" +"Assets:US:ETrade","ITOT","17.00" +"Assets:US:ETrade","USD","5120.50" +"Assets:US:ETrade","VEA","36.00" +"Assets:US:ETrade","VHT","294.00" +"total","GLD","70.00" +"total","ITOT","17.00" +"total","USD","5120.50" +"total","VEA","36.00" +"total","VHT","294.00" +``` + +Bare layout will sometimes display an extra row for the no-symbol commodity, +because of zero amounts (hledger treats zeroes as commodity-less, usually). +This can break `hledger-bar` confusingly (workaround: add a `cur:` query to exclude +the no-symbol row). + +#### Tidy layout +This produces normalised "tidy data" (see ) +where every variable has its own column and each row represents a single data point. +This is the easiest kind of data for other software to consume: + +```cli +$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -Y -O csv --layout=tidy +"account","period","start_date","end_date","commodity","value" +"Assets:US:ETrade","2012","2012-01-01","2012-12-31","GLD","0" +"Assets:US:ETrade","2012","2012-01-01","2012-12-31","ITOT","10.00" +"Assets:US:ETrade","2012","2012-01-01","2012-12-31","USD","337.18" +"Assets:US:ETrade","2012","2012-01-01","2012-12-31","VEA","12.00" +"Assets:US:ETrade","2012","2012-01-01","2012-12-31","VHT","106.00" +"Assets:US:ETrade","2013","2013-01-01","2013-12-31","GLD","70.00" +"Assets:US:ETrade","2013","2013-01-01","2013-12-31","ITOT","18.00" +"Assets:US:ETrade","2013","2013-01-01","2013-12-31","USD","-98.12" +"Assets:US:ETrade","2013","2013-01-01","2013-12-31","VEA","10.00" +"Assets:US:ETrade","2013","2013-01-01","2013-12-31","VHT","18.00" +"Assets:US:ETrade","2014","2014-01-01","2014-12-31","GLD","0" +"Assets:US:ETrade","2014","2014-01-01","2014-12-31","ITOT","-11.00" +"Assets:US:ETrade","2014","2014-01-01","2014-12-31","USD","4881.44" +"Assets:US:ETrade","2014","2014-01-01","2014-12-31","VEA","14.00" +"Assets:US:ETrade","2014","2014-01-01","2014-12-31","VHT","170.00" +``` + +### Some useful balance reports Some frequently used `balance` options/reports are: From 0c44eddd4c50390f1b35ef12fc48323691bd0591 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Fri, 1 Mar 2024 08:09:51 -1000 Subject: [PATCH 23/41] imp:stats: more compact sub-80-width output --- hledger/Hledger/Cli/Commands/Stats.hs | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/hledger/Hledger/Cli/Commands/Stats.hs b/hledger/Hledger/Cli/Commands/Stats.hs index 1b84c3a90..54fe4d3ce 100644 --- a/hledger/Hledger/Cli/Commands/Stats.hs +++ b/hledger/Hledger/Cli/Commands/Stats.hs @@ -68,11 +68,11 @@ stats opts@CliOpts{reportspec_=rspec, progstarttime_} j = do RTSStats{..} <- getRTSStats printf (intercalate ", " - ["Runtime stats : %.2f s elapsed" + ["Runtime stats : %.2f s elapsed" ,"%.0f txns/s" -- ,"%0.0f MB avg live" - ,"%0.0f MB max live" - ,"%0.0f MB peak allocation" + ,"%0.0f MB live" + ,"%0.0f MB alloc" -- ,"(%0.0f MiB" -- ,"%0.0f MiB)" ] ++ "\n") @@ -84,7 +84,7 @@ stats opts@CliOpts{reportspec_=rspec, progstarttime_} j = do else printf (intercalate ", " - ["Runtime stats : %.2f s elapsed" + ["Runtime stats : %.2f s elapsed" ,"%.0f txns/s" ] ++ "\n(add +RTS -T -RTS for more)\n") (realToFrac dt :: Float) @@ -100,24 +100,24 @@ showLedgerStats l today spn = where showRow (label, val) = Group NoLine $ map (Header . textCell TopLeft) [fitText (Just w) (Just w) False True label `T.append` ": ", T.pack val] - w = 25 -- keep synced with labels above + w = 20 -- keep synced with labels above -- w = maximum $ map (T.length . fst) stts (stts, tnum) = ([ ("Main file", path) -- ++ " (from " ++ source ++ ")") ,("Included files", unlines $ drop 1 $ journalFilePaths j) - ,("Transactions span", printf "%s to %s (%d days)" (showstart spn) (showend spn) days) - ,("Last transaction", maybe "none" show lastdate ++ showelapsed lastelapsed) - ,("Transactions", printf "%d (%0.1f per day)" tnum txnrate) - ,("Transactions last 30 days", printf "%d (%0.1f per day)" tnum30 txnrate30) - ,("Transactions last 7 days", printf "%d (%0.1f per day)" tnum7 txnrate7) + ,("Txns span", printf "%s to %s (%d days)" (showstart spn) (showend spn) days) + ,("Last txn", maybe "none" show lastdate ++ showelapsed lastelapsed) + ,("Txns", printf "%d (%0.1f per day)" tnum txnrate) + ,("Txns last 30 days", printf "%d (%0.1f per day)" tnum30 txnrate30) + ,("Txns last 7 days", printf "%d (%0.1f per day)" tnum7 txnrate7) ,("Payees/descriptions", show $ size $ fromList $ map (tdescription) ts) ,("Accounts", printf "%d (depth %d)" acctnum acctdepth) ,("Commodities", printf "%s (%s)" (show $ length cs) (T.intercalate ", " cs)) ,("Market prices", printf "%s (%s)" (show $ length mktprices) (T.intercalate ", " mktpricecommodities)) - -- Transactions this month : %(monthtxns)s (last month in the same period: %(lastmonthtxns)s) - -- Unmarked transactions : %(unmarked)s + -- Txns this month : %(monthtxns)s (last month in the same period: %(lastmonthtxns)s) + -- Unmarked txns : %(unmarked)s -- Days since reconciliation : %(reconcileelapsed)s - -- Days since last transaction : %(recentelapsed)s + -- Days since last txn : %(recentelapsed)s ] ,tnum1) where From c24054455f4aec5a19b76bbf22a2caf0d905221e Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Fri, 1 Mar 2024 08:57:46 -1000 Subject: [PATCH 24/41] imp:stats: be more private by default; update doc The old details (file paths, commodity names) can be shown with -v/--verbose. --- hledger/Hledger/Cli/Commands/Stats.hs | 31 +++++---- hledger/Hledger/Cli/Commands/Stats.md | 51 ++++++++------ hledger/test/journal/balance-assertions.test | 71 ++++++-------------- hledger/test/journal/include.test | 4 +- hledger/test/stats.test | 2 +- 5 files changed, 69 insertions(+), 90 deletions(-) diff --git a/hledger/Hledger/Cli/Commands/Stats.hs b/hledger/Hledger/Cli/Commands/Stats.hs index 54fe4d3ce..342bec686 100644 --- a/hledger/Hledger/Cli/Commands/Stats.hs +++ b/hledger/Hledger/Cli/Commands/Stats.hs @@ -16,6 +16,7 @@ module Hledger.Cli.Commands.Stats ( where import Data.Default (def) +import System.FilePath (takeFileName) import Data.List (intercalate, nub, sortOn) import Data.List.Extra (nubSort) import qualified Data.Map as Map @@ -39,7 +40,8 @@ import Hledger.Cli.Utils (writeOutputLazyText) statsmode = hledgerCommandMode $(embedFileRelative "Hledger/Cli/Commands/Stats.txt") - [flagReq ["output-file","o"] (\s opts -> Right $ setopt "output-file" s opts) "FILE" "write output to FILE." + [ flagNone ["verbose","v"] (setboolopt "verbose") "show more detailed output" + ,flagReq ["output-file","o"] (\s opts -> Right $ setopt "output-file" s opts) "FILE" "write output to FILE." ] [generalflagsgroup1] hiddenflags @@ -48,15 +50,15 @@ statsmode = hledgerCommandMode -- like Register.summarisePostings -- | Print various statistics for the journal. stats :: CliOpts -> Journal -> IO () -stats opts@CliOpts{reportspec_=rspec, progstarttime_} j = do +stats opts@CliOpts{rawopts_=rawopts, reportspec_=rspec, progstarttime_} j = do let today = _rsDay rspec q = _rsQuery rspec l = ledgerFromJournal q j intervalspans = snd $ reportSpanBothDates j rspec - showstats = showLedgerStats l today - (ls, txncounts) = unzip $ map showstats intervalspans + (ls, txncounts) = unzip $ map (showLedgerStats verbose l today) intervalspans numtxns = sum txncounts b = unlinesB ls + verbose = boolopt "verbose" rawopts writeOutputLazyText opts $ TL.init $ TB.toLazyText b t <- getPOSIXTime let dt = t - progstarttime_ @@ -68,8 +70,8 @@ stats opts@CliOpts{reportspec_=rspec, progstarttime_} j = do RTSStats{..} <- getRTSStats printf (intercalate ", " - ["Runtime stats : %.2f s elapsed" - ,"%.0f txns/s" + ["Runtime stats : %.2f s elapsed" -- keep synced + ,"%.0f txns/s" -- -- ,"%0.0f MB avg live" ,"%0.0f MB live" ,"%0.0f MB alloc" @@ -84,7 +86,7 @@ stats opts@CliOpts{reportspec_=rspec, progstarttime_} j = do else printf (intercalate ", " - ["Runtime stats : %.2f s elapsed" + ["Runtime stats : %.2f s elapsed" -- keep ,"%.0f txns/s" ] ++ "\n(add +RTS -T -RTS for more)\n") (realToFrac dt :: Float) @@ -93,8 +95,8 @@ stats opts@CliOpts{reportspec_=rspec, progstarttime_} j = do toMegabytes n = realToFrac n / 1000000 ::Float -- SI preferred definition, 10^6 -- toMebibytes n = realToFrac n / 1048576 ::Float -- traditional computing definition, 2^20 -showLedgerStats :: Ledger -> Day -> DateSpan -> (TB.Builder, Int) -showLedgerStats l today spn = +showLedgerStats :: Bool -> Ledger -> Day -> DateSpan -> (TB.Builder, Int) +showLedgerStats verbose l today spn = (unlinesB $ map (renderRowB def{tableBorders=False, borderSpaces=False} . showRow) stts ,tnum) where @@ -103,8 +105,8 @@ showLedgerStats l today spn = w = 20 -- keep synced with labels above -- w = maximum $ map (T.length . fst) stts (stts, tnum) = ([ - ("Main file", path) -- ++ " (from " ++ source ++ ")") - ,("Included files", unlines $ drop 1 $ journalFilePaths j) + ("Main file", path') -- ++ " (from " ++ source ++ ")") + ,("Included files", if verbose then unlines includedpaths else show (length includedpaths)) ,("Txns span", printf "%s to %s (%d days)" (showstart spn) (showend spn) days) ,("Last txn", maybe "none" show lastdate ++ showelapsed lastelapsed) ,("Txns", printf "%d (%0.1f per day)" tnum txnrate) @@ -112,8 +114,8 @@ showLedgerStats l today spn = ,("Txns last 7 days", printf "%d (%0.1f per day)" tnum7 txnrate7) ,("Payees/descriptions", show $ size $ fromList $ map (tdescription) ts) ,("Accounts", printf "%d (depth %d)" acctnum acctdepth) - ,("Commodities", printf "%s (%s)" (show $ length cs) (T.intercalate ", " cs)) - ,("Market prices", printf "%s (%s)" (show $ length mktprices) (T.intercalate ", " mktpricecommodities)) + ,("Commodities", printf "%s%s" (show $ length cs) (if verbose then " (" <> T.intercalate ", " cs <> ")" else "")) + ,("Market prices", printf "%s%s" (show $ length mktprices) (if verbose then " (" <> T.intercalate ", " mktpricecommodities <> ")" else "")) -- Txns this month : %(monthtxns)s (last month in the same period: %(lastmonthtxns)s) -- Unmarked txns : %(unmarked)s -- Days since reconciliation : %(reconcileelapsed)s @@ -122,7 +124,8 @@ showLedgerStats l today spn = ,tnum1) where j = ljournal l - path = journalFilePath j + path' = if verbose then path else ".../" <> takeFileName path where path = journalFilePath j + includedpaths = drop 1 $ journalFilePaths j ts = sortOn tdate $ filter (spanContainsDate spn . tdate) $ jtxns j as = nub $ map paccount $ concatMap tpostings ts cs = either error' Map.keys $ commodityStylesFromAmounts $ concatMap (amountsRaw . pamount) $ concatMap tpostings ts -- PARTIAL: diff --git a/hledger/Hledger/Cli/Commands/Stats.md b/hledger/Hledger/Cli/Commands/Stats.md index 4bcc0731d..85a0227cc 100644 --- a/hledger/Hledger/Cli/Commands/Stats.md +++ b/hledger/Hledger/Cli/Commands/Stats.md @@ -4,36 +4,43 @@ Show journal and performance statistics. _FLAGS -The stats command displays summary information for the whole journal, or +The stats command shows summary information for the whole journal, or a matched part of it. With a [reporting interval](#reporting-interval), it shows a report for each report period. -At the end, it shows (in the terminal) the overall run time and number of -transactions processed per second. Note these are approximate and will vary -based on machine, current load, data size, hledger version, haskell lib -versions, GHC version.. but they may be of interest. The `stats` command's -run time is similar to that of a single-column balance report. +The default output is fairly impersonal, though it reveals the main file name. +With `-v/--verbose`, more details are shown, like file paths, included files, +and commodity names. + +It also shows some run time statistics: + +- elapsed time +- throughput: the number of transactions processed per second +- live: the peak memory in use by the program to do its work +- alloc: the peak memory allocation from the OS as seen by GHC. + Measuring this externally, eg with GNU time, is more accurate; + usually that will be a larger number; sometimes (with swapping?) smaller. + +The `stats` command's run time is similar to that of a balance report. Example: ```cli -$ hledger stats -f examples/1000x1000x10.journal -Main file : /Users/simon/src/hledger/examples/1000x1000x10.journal -Included files : -Transactions span : 2000-01-01 to 2002-09-27 (1000 days) -Last transaction : 2002-09-26 (6995 days ago) -Transactions : 1000 (1.0 per day) -Transactions last 30 days: 0 (0.0 per day) -Transactions last 7 days : 0 (0.0 per day) -Payees/descriptions : 1000 -Accounts : 1000 (depth 10) -Commodities : 26 (A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X, Y, Z) -Market prices : 1000 (A) - -Run time : 0.12 s -Throughput : 8342 txns/s +$ hledger stats -f examples/1ktxns-1kaccts.journal +Main file : .../1ktxns-1kaccts.journal +Included files : 0 +Txns span : 2000-01-01 to 2002-09-27 (1000 days) +Last txn : 2002-09-26 (7827 days ago) +Txns : 1000 (1.0 per day) +Txns last 30 days : 0 (0.0 per day) +Txns last 7 days : 0 (0.0 per day) +Payees/descriptions : 1000 +Accounts : 1000 (depth 10) +Commodities : 26 +Market prices : 1000 +Runtime stats : 0.12 s elapsed, 8266 txns/s, 4 MB live, 16 MB alloc ``` This command supports the [-o/--output-file](hledger.html#output-destination) option -(but not [-O/--output-format](hledger.html#output-format) selection). +(but not [-O/--output-format](hledger.html#output-format)). diff --git a/hledger/test/journal/balance-assertions.test b/hledger/test/journal/balance-assertions.test index 68782e486..c746e75da 100755 --- a/hledger/test/journal/balance-assertions.test +++ b/hledger/test/journal/balance-assertions.test @@ -15,9 +15,7 @@ b $-1 = $-3 (b) $1 = $-2 -$ hledger -f - stats -> /Transactions/ ->=0 +$ hledger -f - check # ** 2. same entries as 1 but different parse order, assertion should still pass based on date < @@ -34,9 +32,7 @@ $ hledger -f - stats a $1 =$2 b $-1 =$-2 -$ hledger -f - stats -> /Transactions/ ->=0 +$ hledger -f - check # ** 3. like 1 but switch order of postings in last entry, # assertion should fail and exit code should be non zero @@ -54,7 +50,7 @@ $ hledger -f - stats (b) $1 = $-2 b $-1 = $-3 -$ hledger -f - stats +$ hledger -f - check >2 /Error: -:11:12/ >=1 @@ -63,9 +59,7 @@ $ hledger -f - stats 2013/1/1 (a) 1 =1 -$ hledger -f - stats -> /Transactions/ ->=0 +$ hledger -f - check # ** 5. should work for fractional amount with trailing zeros < @@ -81,9 +75,7 @@ $ hledger -f - stats a $0.7 =$2 b =-$2 -$ hledger -f - stats -> /Transactions/ ->=0 +$ hledger -f - check # ** 6. assertions currently check only a single commodity's balance, like Ledger < @@ -93,9 +85,7 @@ $ hledger -f - stats (a) 0 = A1 (a) C0 = D0 -$ hledger -f - stats -> /Transactions/ ->=0 +$ hledger -f - check # ** 7. balances should accumulate (#195) < @@ -106,9 +96,7 @@ $ hledger -f - stats 1/2 (a) 3F = 4F -$ hledger -f - stats -> !/assertion failed/ ->=0 +$ hledger -f - check # ** 8. what should happen here ? Currently, # in a, 3.4 EUR @@ $5.6 and -3.4 EUR cancel out (wrong ?) @@ -128,9 +116,7 @@ $ hledger -f - stats # a $0.1 =$1.30 # b =-$1.30 -# $ hledger -f - stats -# > /Transactions/ -# >=0 +# $ hledger -f - check # ** 8. Using balance assignment to set balances. < @@ -146,9 +132,7 @@ $ hledger -f - stats a $10 =$11.3 b =$-11.3 -$ hledger -f - stats -> /Transactions/ ->=0 +$ hledger -f - check # ** 9. Multiple assertions for an account in the same transaction. @@ -166,9 +150,7 @@ $ hledger -f - stats b $-1 = $-3 b $-1 = $-4 -$ hledger -f - stats -> /Transactions/ ->=0 +$ hledger -f - check # ** 10. Multiple assertions and assignments for an account in the same transaction. < @@ -196,9 +178,7 @@ $ hledger -f - stats c = 50 B c = 50 A -$ hledger -f - stats -> /Transactions/ ->=0 +$ hledger -f - check # ** 11. Assignments and virtual postings < @@ -214,16 +194,15 @@ $ hledger -f - stats [a] = $5 b = $9 -$ hledger -f - stats -> /Transactions/ ->=0 +$ hledger -f - check + # ** 12. Having both assignments and posting dates is not supported. < 2013/1/1 a $1 =$1 b =$-1 ; date:2012/1/1 -$ hledger -f - stats +$ hledger -f - check >2 /Balance assignments and custom posting dates may not be combined/ >=1 @@ -247,9 +226,7 @@ $ hledger -f - stats [d] 10 -$ hledger -f - stats -> /Transactions/ ->=0 +$ hledger -f - check # ** 14. Mix different commodities < @@ -261,9 +238,7 @@ $ hledger -f - stats a $-1 = $0 b -$ hledger -f - stats -> /Transactions/ ->=0 +$ hledger -f - check # ** 15. Mix different commodities and assignments < @@ -282,9 +257,7 @@ $ hledger -f - stats a b = 0 zorkmids -$ hledger -f - stats -> /Transactions/ ->=0 +$ hledger -f - check # ** 16. Total assertions (==) parse correctly < @@ -295,9 +268,7 @@ $ hledger -f - stats 2016/1/2 a == $1 -$ hledger -f - stats -> /Transactions/ ->=0 +$ hledger -f - check # ** 17. Total assertions consider entire multicommodity amount < @@ -312,7 +283,7 @@ $ hledger -f - stats 2016/1/3 a 0 == $1 -$ hledger -f - stats +$ hledger -f - check >2 /Error: -:10:15:/ >=1 @@ -331,9 +302,7 @@ $ hledger -f - stats b 0 = $-1 b 0 = 0 zorkmids -$ hledger -f - stats -> /Transactions/ ->=0 +$ hledger -f - check # ** 19. Cost is ignored when checking balance assertions. < diff --git a/hledger/test/journal/include.test b/hledger/test/journal/include.test index cc8cb6244..ad4443707 100644 --- a/hledger/test/journal/include.test +++ b/hledger/test/journal/include.test @@ -74,12 +74,12 @@ $ printf '2018/01/01\n (A) 1\n' >included.journal; HOME="$PWD" hledger -f - pr # They use different file names so a single concurrent shelltest invocation will be fine. # ** 7. test that order of include files is maintained -$ printf 'include _b\n' >_a; touch _b; hledger -f _a stats | grep _ | sed -e 's%.*/%%'; rm -rf _a _b +$ printf 'include _b\n' >_a; touch _b; hledger -f _a stats -v | grep _ | sed -e 's%.*/%%'; rm -rf _a _b _a _b # ** 8. and with --auto code path -$ printf 'include _d\n=\n' >_c; touch _d; hledger -f _c stats --auto | grep _ | sed -e 's%.*/%%'; rm -rf _c _d +$ printf 'include _d\n=\n' >_c; touch _d; hledger -f _c stats -v --auto | grep _ | sed -e 's%.*/%%'; rm -rf _c _d _c _d diff --git a/hledger/test/stats.test b/hledger/test/stats.test index cdb7945b0..dede1acad 100644 --- a/hledger/test/stats.test +++ b/hledger/test/stats.test @@ -7,6 +7,6 @@ $ hledger -f- stats < include a.j include b.j -$ touch a.j b.j; hledger -f- stats; rm -f a.j b.j +$ touch a.j b.j; hledger -f- stats -v; rm -f a.j b.j > /Included files.*\/a\.j .*\/b\.j/ From 7db8e01200db7fc22bf03e50e5bda519251fbdd6 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Fri, 1 Mar 2024 18:08:34 -1000 Subject: [PATCH 25/41] imp:stats: with multiple reports, add a blank line before runtime stats --- hledger/Hledger/Cli/Commands/Stats.hs | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/hledger/Hledger/Cli/Commands/Stats.hs b/hledger/Hledger/Cli/Commands/Stats.hs index 342bec686..ff0a32022 100644 --- a/hledger/Hledger/Cli/Commands/Stats.hs +++ b/hledger/Hledger/Cli/Commands/Stats.hs @@ -52,14 +52,15 @@ statsmode = hledgerCommandMode stats :: CliOpts -> Journal -> IO () stats opts@CliOpts{rawopts_=rawopts, reportspec_=rspec, progstarttime_} j = do let today = _rsDay rspec + verbose = boolopt "verbose" rawopts q = _rsQuery rspec l = ledgerFromJournal q j intervalspans = snd $ reportSpanBothDates j rspec + ismultiperiod = length intervalspans > 1 (ls, txncounts) = unzip $ map (showLedgerStats verbose l today) intervalspans numtxns = sum txncounts - b = unlinesB ls - verbose = boolopt "verbose" rawopts - writeOutputLazyText opts $ TL.init $ TB.toLazyText b + txt = (if ismultiperiod then id else TL.init) $ TB.toLazyText $ unlinesB ls + writeOutputLazyText opts txt t <- getPOSIXTime let dt = t - progstarttime_ rtsStatsEnabled <- getRTSStatsEnabled From afd009db9e0a46c988b013ff579ee15378c817af Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Fri, 1 Mar 2024 09:13:00 -1000 Subject: [PATCH 26/41] ;doc: update command help --- hledger/Hledger/Cli/Commands/Balance.txt | 257 ++++++++++++----------- hledger/Hledger/Cli/Commands/Close.txt | 4 + hledger/Hledger/Cli/Commands/Stats.txt | 55 ++--- 3 files changed, 167 insertions(+), 149 deletions(-) diff --git a/hledger/Hledger/Cli/Commands/Balance.txt b/hledger/Hledger/Cli/Commands/Balance.txt index 1e01a6f12..2a16f9593 100644 --- a/hledger/Hledger/Cli/Commands/Balance.txt +++ b/hledger/Hledger/Cli/Commands/Balance.txt @@ -35,6 +35,7 @@ balance can show.. - or value of balance changes (-V) - or change of balance values (--valuechange) - or unrealised capital gain/loss (--gain) +- or balance changes from sibling postings (--related/-r) - or postings count (--count) ..in.. @@ -70,9 +71,6 @@ with output formats txt, csv, tsv (Added in 1.32), json, and (multi-period reports only:) html. In txt output in a colour-supporting terminal, negative amounts are shown in red. -The --related/-r flag shows the balance of the other postings in the -transactions of the postings which would normally be shown. - Simple balance report With no arguments, balance shows a list of all accounts and their change @@ -343,7 +341,9 @@ Multi-period reports with many periods can be too wide for easy viewing in the terminal. Here are some ways to handle that: - Hide the totals row with -N/--no-total -- Convert to a single currency with -V +- Filter to a single currency with cur: +- Convert to a single currency with -V [--infer-market-price] +- Use a more compact layout like --layout=bare - Maximize the terminal window - Reduce the terminal's font size - View with a pager like less, eg: @@ -415,13 +415,13 @@ The basic calculation to perform for each table cell. It is one of: Accumulation type -How amounts should accumulate across report periods. Another way to say -it: which time period's postings should contribute to each cell's -calculation. It is one of: +How amounts should accumulate across a report's subperiods/columns. +Another way to say it: which time period's postings should contribute to +each cell's calculation. It is one of: - --change : calculate with postings from column start to column end, ie "just this column". Typically used to see revenues/expenses. - (default for balance, incomestatement) + (default for balance, cashflow, incomestatement) - --cumulative : calculate with postings from report start to column end, ie "previous columns plus this column". Typically used to show @@ -431,7 +431,7 @@ calculation. It is one of: column end, ie "all postings from before report start date until this column's end". Typically used to see historical end balances of assets/liabilities/equity. (default for balancesheet, - balancesheetequity, cashflow) + balancesheetequity) Valuation type @@ -659,35 +659,35 @@ defined in your journal. Budgeting vs forecasting ---budget and --forecast both use the periodic transaction rules in the +--forecast and --budget both use the periodic transaction rules in the journal to generate temporary transactions for reporting purposes. However they are separate features - though you can use both at the same time if you want. Here are some differences between them: -1. --budget is a command-specific option; it selects the budget report. + ----------------------------------------------------------------------- + --forecast --budget + -------------------------------------- -------------------------------- + is a general option; it enables is a balance command option; it + forecasting with all reports selects the balance report's + budget mode - --forecast is a general option; forecasting works with all reports. + generates visible transactions which generates invisible transactions + appear in reports which produce goal amounts -2. --budget uses all periodic rules; --budget=DESCPAT uses just the - rules matched by DESCPAT. + generates forecast transactions from generates budget goal + after the last regular transaction, to transactions throughout the + the end of the report period; or with report period, optionally + an argument --forecast=PERIODEXPR restricted by periods specified + generates them throughout the in the periodic transaction + specified period, both optionally rules + restricted by periods specified in the + periodic transaction rules - --forecast uses all periodic rules. - -3. --budget's budget goal transactions are invisible, except that they - produce goal amounts. - - --forecast's forecast transactions are visible, and appear in - reports. - -4. --budget generates budget goal transactions throughout the report - period, optionally restricted by periods specified in the periodic - transaction rules. - - --forecast generates forecast transactions from after the last - regular transaction, to the end of the report period; while - --forecast=PERIODEXPR generates them throughout the specified - period; both optionally restricted by periods specified in the - periodic transaction rules. + uses all periodic rules uses all periodic rules; or with + an argument --budget=DESCPAT + uses just the rules matched by + DESCPAT + ----------------------------------------------------------------------- Balance report layout @@ -704,8 +704,8 @@ four possible values: - --layout=tidy: data is normalised to easily-consumed "tidy" form, with one row per data value -Here are the --layout modes supported by each output format; note only -CSV output supports all of them: +Here are the --layout modes supported by each output format Only CSV +output supports all of them: - txt csv html json sql ------ ----- ----- ------ ------ ----- @@ -716,115 +716,122 @@ CSV output supports all of them: Examples: -- Wide layout. With many commodities, reports can be very wide: +Wide layout - $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide - Balance changes in 2012-01-01..2014-12-31: +With many commodities, reports can be very wide: - || 2012 2013 2014 Total - ==================++==================================================================================================================================================================================================================== - Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT 70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT 70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT - ------------------++-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- - || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT 70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT 70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT +$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide +Balance changes in 2012-01-01..2014-12-31: -- Limited wide layout. A width limit reduces the width, but some - commodities will be hidden: + || 2012 2013 2014 Total +==================++==================================================================================================================================================================================================================== + Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT 70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT 70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT +------------------++-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- + || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT 70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT 70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT - $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide,32 - Balance changes in 2012-01-01..2014-12-31: +A width limit reduces the width, but some commodities will be hidden: - || 2012 2013 2014 Total - ==================++=========================================================================================================================== - Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. -11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more.. - ------------------++--------------------------------------------------------------------------------------------------------------------------- - || 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. -11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more.. +$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide,32 +Balance changes in 2012-01-01..2014-12-31: -- Tall layout. Each commodity gets a new line (may be different in - each column), and account names are repeated: + || 2012 2013 2014 Total +==================++=========================================================================================================================== + Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. -11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more.. +------------------++--------------------------------------------------------------------------------------------------------------------------- + || 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. -11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more.. - $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=tall - Balance changes in 2012-01-01..2014-12-31: +Tall layout - || 2012 2013 2014 Total - ==================++================================================== - Assets:US:ETrade || 10.00 ITOT 70.00 GLD -11.00 ITOT 70.00 GLD - Assets:US:ETrade || 337.18 USD 18.00 ITOT 4881.44 USD 17.00 ITOT - Assets:US:ETrade || 12.00 VEA -98.12 USD 14.00 VEA 5120.50 USD - Assets:US:ETrade || 106.00 VHT 10.00 VEA 170.00 VHT 36.00 VEA - Assets:US:ETrade || 18.00 VHT 294.00 VHT - ------------------++-------------------------------------------------- - || 10.00 ITOT 70.00 GLD -11.00 ITOT 70.00 GLD - || 337.18 USD 18.00 ITOT 4881.44 USD 17.00 ITOT - || 12.00 VEA -98.12 USD 14.00 VEA 5120.50 USD - || 106.00 VHT 10.00 VEA 170.00 VHT 36.00 VEA - || 18.00 VHT 294.00 VHT +Each commodity gets a new line (may be different in each column), and +account names are repeated: -- Bare layout. Commodity symbols are kept in one column, each - commodity gets its own report row, account names are repeated: +$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=tall +Balance changes in 2012-01-01..2014-12-31: - $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=bare - Balance changes in 2012-01-01..2014-12-31: + || 2012 2013 2014 Total +==================++================================================== + Assets:US:ETrade || 10.00 ITOT 70.00 GLD -11.00 ITOT 70.00 GLD + Assets:US:ETrade || 337.18 USD 18.00 ITOT 4881.44 USD 17.00 ITOT + Assets:US:ETrade || 12.00 VEA -98.12 USD 14.00 VEA 5120.50 USD + Assets:US:ETrade || 106.00 VHT 10.00 VEA 170.00 VHT 36.00 VEA + Assets:US:ETrade || 18.00 VHT 294.00 VHT +------------------++-------------------------------------------------- + || 10.00 ITOT 70.00 GLD -11.00 ITOT 70.00 GLD + || 337.18 USD 18.00 ITOT 4881.44 USD 17.00 ITOT + || 12.00 VEA -98.12 USD 14.00 VEA 5120.50 USD + || 106.00 VHT 10.00 VEA 170.00 VHT 36.00 VEA + || 18.00 VHT 294.00 VHT - || Commodity 2012 2013 2014 Total - ==================++============================================= - Assets:US:ETrade || GLD 0 70.00 0 70.00 - Assets:US:ETrade || ITOT 10.00 18.00 -11.00 17.00 - Assets:US:ETrade || USD 337.18 -98.12 4881.44 5120.50 - Assets:US:ETrade || VEA 12.00 10.00 14.00 36.00 - Assets:US:ETrade || VHT 106.00 18.00 170.00 294.00 - ------------------++--------------------------------------------- - || GLD 0 70.00 0 70.00 - || ITOT 10.00 18.00 -11.00 17.00 - || USD 337.18 -98.12 4881.44 5120.50 - || VEA 12.00 10.00 14.00 36.00 - || VHT 106.00 18.00 170.00 294.00 +Bare layout -- Bare layout also affects CSV output, which is useful for producing - data that is easier to consume, eg for making charts: +Commodity symbols are kept in one column, each commodity has its own +row, amounts are bare numbers, account names are repeated: - $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -O csv --layout=bare - "account","commodity","balance" - "Assets:US:ETrade","GLD","70.00" - "Assets:US:ETrade","ITOT","17.00" - "Assets:US:ETrade","USD","5120.50" - "Assets:US:ETrade","VEA","36.00" - "Assets:US:ETrade","VHT","294.00" - "total","GLD","70.00" - "total","ITOT","17.00" - "total","USD","5120.50" - "total","VEA","36.00" - "total","VHT","294.00" +$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=bare +Balance changes in 2012-01-01..2014-12-31: -- Note: bare layout will sometimes display an extra row for the - no-symbol commodity, because of zero amounts (hledger treats zeroes - as commodity-less, usually). This can break hledger-bar confusingly - (workaround: add a cur: query to exclude the no-symbol row). + || Commodity 2012 2013 2014 Total +==================++============================================= + Assets:US:ETrade || GLD 0 70.00 0 70.00 + Assets:US:ETrade || ITOT 10.00 18.00 -11.00 17.00 + Assets:US:ETrade || USD 337.18 -98.12 4881.44 5120.50 + Assets:US:ETrade || VEA 12.00 10.00 14.00 36.00 + Assets:US:ETrade || VHT 106.00 18.00 170.00 294.00 +------------------++--------------------------------------------- + || GLD 0 70.00 0 70.00 + || ITOT 10.00 18.00 -11.00 17.00 + || USD 337.18 -98.12 4881.44 5120.50 + || VEA 12.00 10.00 14.00 36.00 + || VHT 106.00 18.00 170.00 294.00 -- Tidy layout produces normalised "tidy data", where every variable - has its own column and each row represents a single data point. See - https://cran.r-project.org/web/packages/tidyr/vignettes/tidy-data.html - for more. This is the easiest kind of data for other software to - consume. Here's how it looks: +Bare layout also affects CSV output, which is useful for producing data +that is easier to consume, eg for making charts: - $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -Y -O csv --layout=tidy - "account","period","start_date","end_date","commodity","value" - "Assets:US:ETrade","2012","2012-01-01","2012-12-31","GLD","0" - "Assets:US:ETrade","2012","2012-01-01","2012-12-31","ITOT","10.00" - "Assets:US:ETrade","2012","2012-01-01","2012-12-31","USD","337.18" - "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VEA","12.00" - "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VHT","106.00" - "Assets:US:ETrade","2013","2013-01-01","2013-12-31","GLD","70.00" - "Assets:US:ETrade","2013","2013-01-01","2013-12-31","ITOT","18.00" - "Assets:US:ETrade","2013","2013-01-01","2013-12-31","USD","-98.12" - "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VEA","10.00" - "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VHT","18.00" - "Assets:US:ETrade","2014","2014-01-01","2014-12-31","GLD","0" - "Assets:US:ETrade","2014","2014-01-01","2014-12-31","ITOT","-11.00" - "Assets:US:ETrade","2014","2014-01-01","2014-12-31","USD","4881.44" - "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VEA","14.00" - "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VHT","170.00" +$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -O csv --layout=bare +"account","commodity","balance" +"Assets:US:ETrade","GLD","70.00" +"Assets:US:ETrade","ITOT","17.00" +"Assets:US:ETrade","USD","5120.50" +"Assets:US:ETrade","VEA","36.00" +"Assets:US:ETrade","VHT","294.00" +"total","GLD","70.00" +"total","ITOT","17.00" +"total","USD","5120.50" +"total","VEA","36.00" +"total","VHT","294.00" -Useful balance reports +Bare layout will sometimes display an extra row for the no-symbol +commodity, because of zero amounts (hledger treats zeroes as +commodity-less, usually). This can break hledger-bar confusingly +(workaround: add a cur: query to exclude the no-symbol row). + +Tidy layout + +This produces normalised "tidy data" (see +https://cran.r-project.org/web/packages/tidyr/vignettes/tidy-data.html) +where every variable has its own column and each row represents a single +data point. This is the easiest kind of data for other software to +consume: + +$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -Y -O csv --layout=tidy +"account","period","start_date","end_date","commodity","value" +"Assets:US:ETrade","2012","2012-01-01","2012-12-31","GLD","0" +"Assets:US:ETrade","2012","2012-01-01","2012-12-31","ITOT","10.00" +"Assets:US:ETrade","2012","2012-01-01","2012-12-31","USD","337.18" +"Assets:US:ETrade","2012","2012-01-01","2012-12-31","VEA","12.00" +"Assets:US:ETrade","2012","2012-01-01","2012-12-31","VHT","106.00" +"Assets:US:ETrade","2013","2013-01-01","2013-12-31","GLD","70.00" +"Assets:US:ETrade","2013","2013-01-01","2013-12-31","ITOT","18.00" +"Assets:US:ETrade","2013","2013-01-01","2013-12-31","USD","-98.12" +"Assets:US:ETrade","2013","2013-01-01","2013-12-31","VEA","10.00" +"Assets:US:ETrade","2013","2013-01-01","2013-12-31","VHT","18.00" +"Assets:US:ETrade","2014","2014-01-01","2014-12-31","GLD","0" +"Assets:US:ETrade","2014","2014-01-01","2014-12-31","ITOT","-11.00" +"Assets:US:ETrade","2014","2014-01-01","2014-12-31","USD","4881.44" +"Assets:US:ETrade","2014","2014-01-01","2014-12-31","VEA","14.00" +"Assets:US:ETrade","2014","2014-01-01","2014-12-31","VHT","170.00" + +Some useful balance reports Some frequently used balance options/reports are: diff --git a/hledger/Hledger/Cli/Commands/Close.txt b/hledger/Hledger/Cli/Commands/Close.txt index 36378939c..adf0e7612 100644 --- a/hledger/Hledger/Cli/Commands/Close.txt +++ b/hledger/Hledger/Cli/Commands/Close.txt @@ -132,6 +132,10 @@ balances in an opening transaction. These provide useful error checking, but you can ignore them temporarily with -I, or remove them if you prefer. +Single-commodity, subaccount-exclusive balance assertions (=) are +generated by default. This can be changed with --assertion-type='==*' +(eg). + When running close you should probably avoid using -C, -R, status: (filtering by status or realness) or --auto (generating postings), since the generated balance assertions would then require these. diff --git a/hledger/Hledger/Cli/Commands/Stats.txt b/hledger/Hledger/Cli/Commands/Stats.txt index 5dc1293e6..8708f4953 100644 --- a/hledger/Hledger/Cli/Commands/Stats.txt +++ b/hledger/Hledger/Cli/Commands/Stats.txt @@ -4,34 +4,41 @@ Show journal and performance statistics. _FLAGS -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 +The stats command shows summary information for the whole journal, or a +matched part of it. With a reporting interval, it shows a report for each report period. -At the end, it shows (in the terminal) the overall run time and number -of transactions processed per second. Note these are approximate and -will vary based on machine, current load, data size, hledger version, -haskell lib versions, GHC version.. but they may be of interest. The -stats command's run time is similar to that of a single-column balance -report. +The default output is fairly impersonal, though it reveals the main file +name. With -v/--verbose, more details are shown, like file paths, +included files, and commodity names. + +It also shows some run time statistics: + +- elapsed time +- throughput: the number of transactions processed per second +- live: the peak memory in use by the program to do its work +- alloc: the peak memory allocation from the OS as seen by GHC. + Measuring this externally, eg with GNU time, is more accurate; + usually that will be a larger number; sometimes (with swapping?) + smaller. + +The stats command's run time is similar to that of a balance report. Example: -$ hledger stats -f examples/1000x1000x10.journal -Main file : /Users/simon/src/hledger/examples/1000x1000x10.journal -Included files : -Transactions span : 2000-01-01 to 2002-09-27 (1000 days) -Last transaction : 2002-09-26 (6995 days ago) -Transactions : 1000 (1.0 per day) -Transactions last 30 days: 0 (0.0 per day) -Transactions last 7 days : 0 (0.0 per day) -Payees/descriptions : 1000 -Accounts : 1000 (depth 10) -Commodities : 26 (A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X, Y, Z) -Market prices : 1000 (A) - -Run time : 0.12 s -Throughput : 8342 txns/s +$ hledger stats -f examples/1ktxns-1kaccts.journal +Main file : .../1ktxns-1kaccts.journal +Included files : 0 +Txns span : 2000-01-01 to 2002-09-27 (1000 days) +Last txn : 2002-09-26 (7827 days ago) +Txns : 1000 (1.0 per day) +Txns last 30 days : 0 (0.0 per day) +Txns last 7 days : 0 (0.0 per day) +Payees/descriptions : 1000 +Accounts : 1000 (depth 10) +Commodities : 26 +Market prices : 1000 +Runtime stats : 0.12 s elapsed, 8266 txns/s, 4 MB live, 16 MB alloc This command supports the -o/--output-file option (but not --O/--output-format selection). +-O/--output-format). From b7d7dda46343301fe0edc48bfe1d5b4ba13740c0 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Fri, 1 Mar 2024 17:22:07 -1000 Subject: [PATCH 27/41] dev: rename query-expr.test --- hledger/test/{query-bool.test => query-expr.test} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename hledger/test/{query-bool.test => query-expr.test} (100%) diff --git a/hledger/test/query-bool.test b/hledger/test/query-expr.test similarity index 100% rename from hledger/test/query-bool.test rename to hledger/test/query-expr.test From 3ca208a3b6b91ca00aeeb22d228c2f8c909efe7f Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Fri, 1 Mar 2024 18:07:13 -1000 Subject: [PATCH 28/41] fix:queries: fix OR-ing open-ended dates, spanUnion; add spanExtend [#2177] --- hledger-lib/Hledger/Data/Dates.hs | 99 ++++++++++++++------ hledger-lib/Hledger/Reports/ReportOptions.hs | 2 +- hledger/hledger.m4.md | 2 - hledger/test/query-expr.test | 12 +++ 4 files changed, 84 insertions(+), 31 deletions(-) diff --git a/hledger-lib/Hledger/Data/Dates.hs b/hledger-lib/Hledger/Data/Dates.hs index a7e90bc6f..d131bc6e3 100644 --- a/hledger-lib/Hledger/Data/Dates.hs +++ b/hledger-lib/Hledger/Data/Dates.hs @@ -63,6 +63,7 @@ module Hledger.Data.Dates ( spanIntersect, spansIntersect, spanDefaultsFrom, + spanExtend, spanUnion, spansUnion, daysSpan, @@ -314,8 +315,8 @@ groupByDateSpan showempty date colspans = where groupByCols [] _ = [] groupByCols (c:cs) [] = if showempty then (c, []) : groupByCols cs [] else [] - groupByCols (c:cs) ps = (c, map snd matches) : groupByCols cs later - where (matches, later) = span ((spanEnd c >) . Just . fst) ps + groupByCols (c:cs) ps = (c, map snd colps) : groupByCols cs laterps + where (colps, laterps) = span ((spanEnd c >) . Just . fst) ps beforeStart = maybe (const False) (>) $ spanStart =<< headMay colspans @@ -324,40 +325,82 @@ spansIntersect [] = nulldatespan spansIntersect [d] = d spansIntersect (d:ds) = d `spanIntersect` (spansIntersect ds) --- | Calculate the intersection of two datespans. --- --- For non-intersecting spans, gives an empty span beginning on the second's start date: --- >>> DateSpan (Just $ Flex $ fromGregorian 2018 01 01) (Just $ Flex $ fromGregorian 2018 01 03) `spanIntersect` DateSpan (Just $ Flex $ fromGregorian 2018 01 03) (Just $ Flex $ fromGregorian 2018 01 05) --- DateSpan 2018-01-03..2018-01-02 -spanIntersect (DateSpan b1 e1) (DateSpan b2 e2) = DateSpan b e - where - b = latest b1 b2 - e = earliest e1 e2 - --- | Fill any unspecified dates in the first span with the dates from --- the second one. Sort of a one-way spanIntersect. -spanDefaultsFrom (DateSpan a1 b1) (DateSpan a2 b2) = DateSpan a b - where a = if isJust a1 then a1 else a2 - b = if isJust b1 then b1 else b2 - -- | Calculate the union of a number of datespans. spansUnion [] = nulldatespan spansUnion [d] = d spansUnion (d:ds) = d `spanUnion` (spansUnion ds) +-- | Calculate the intersection of two datespans. +-- +-- For non-intersecting spans, gives an empty span beginning on the second's start date: +-- >>> DateSpan (Just $ Flex $ fromGregorian 2018 01 01) (Just $ Flex $ fromGregorian 2018 01 03) `spanIntersect` DateSpan (Just $ Flex $ fromGregorian 2018 01 03) (Just $ Flex $ fromGregorian 2018 01 05) +-- DateSpan 2018-01-03..2018-01-02 +spanIntersect (DateSpan b1 e1) (DateSpan b2 e2) = DateSpan (laterDefinite b1 b2) (earlierDefinite e1 e2) + +-- | Fill any unspecified dates in the first span with the dates from +-- the second one (if specified there). Sort of a one-way spanIntersect. +spanDefaultsFrom (DateSpan a1 b1) (DateSpan a2 b2) = DateSpan a b + where a = if isJust a1 then a1 else a2 + b = if isJust b1 then b1 else b2 + -- | Calculate the union of two datespans. -spanUnion (DateSpan b1 e1) (DateSpan b2 e2) = DateSpan b e - where - b = earliest b1 b2 - e = latest e1 e2 +-- If either span is open-ended, the union will be too. +-- +-- >>> ys2024 = fromGregorian 2024 01 01 +-- >>> ys2025 = fromGregorian 2025 01 01 +-- >>> to2024 = DateSpan Nothing (Just $ Exact ys2024) +-- >>> in2024 = DateSpan (Just $ Exact ys2024) (Just $ Exact ys2025) +-- >>> spanUnion to2024 in2024 +-- DateSpan ..2024-12-31 +-- >>> spanUnion in2024 to2024 +-- DateSpan ..2024-12-31 +spanUnion (DateSpan b1 e1) (DateSpan b2 e2) = DateSpan (earlier b1 b2) (later e1 e2) -latest d Nothing = d -latest Nothing d = d -latest (Just d1) (Just d2) = Just $ max d1 d2 +-- | Extend the first span to include any definite end dates of the second. +-- Unlike spanUnion, open ends in the second are ignored. +-- If the first span was open-ended, it still will be after being extended. +-- +-- >>> ys2024 = fromGregorian 2024 01 01 +-- >>> ys2025 = fromGregorian 2025 01 01 +-- >>> to2024 = DateSpan Nothing (Just $ Exact ys2024) +-- >>> all2024 = DateSpan (Just $ Exact ys2024) (Just $ Exact ys2025) +-- >>> partof2024 = DateSpan (Just $ Exact $ fromGregorian 2024 03 01) (Just $ Exact $ fromGregorian 2024 09 01) +-- >>> spanExtend to2024 all2024 +-- DateSpan 2024 +-- >>> spanExtend all2024 to2024 +-- DateSpan 2024 +-- >>> spanExtend partof2024 all2024 +-- DateSpan 2024 +-- >>> spanExtend all2024 partof2024 +-- DateSpan 2024 +-- +spanExtend (DateSpan b1 e1) (DateSpan b2 e2) = DateSpan (earlierDefinite b1 b2) (laterDefinite e1 e2) -earliest d Nothing = d -earliest Nothing d = d -earliest (Just d1) (Just d2) = Just $ min d1 d2 +-- | Pick the earlier of two DateSpan starts, treating Nothing as infinitely early. +-- An Exact and Flex with the same date are considered equal; the first argument wins. +earlier :: Maybe EFDay -> Maybe EFDay -> Maybe EFDay +earlier = min + +-- | Pick the later of two DateSpan starts, treating Nothing as infinitely late. +-- An Exact and Flex with the same date are considered equal; the second argument wins. +later :: Maybe EFDay -> Maybe EFDay -> Maybe EFDay +later _ Nothing = Nothing +later Nothing _ = Nothing +later d1 d2 = max d1 d2 + +-- | Pick the earlier of two DateSpan ends that is a definite date (if any). +-- An Exact and Flex with the same date are considered equal; the first argument wins. +earlierDefinite :: Maybe EFDay -> Maybe EFDay -> Maybe EFDay +earlierDefinite d1 Nothing = d1 +earlierDefinite Nothing d2 = d2 +earlierDefinite d1 d2 = min d1 d2 + +-- | Pick the later of two DateSpan ends that is a definite date (if any). +-- An Exact and Flex with the same date are considered equal; the second argument wins. +laterDefinite :: Maybe EFDay -> Maybe EFDay -> Maybe EFDay +laterDefinite d1 Nothing = d1 +laterDefinite Nothing d2 = d2 +laterDefinite d1 d2 = max d1 d2 -- | Calculate the minimal DateSpan containing all of the given Days (in the -- usual exclusive-end-date sense: beginning on the earliest, and ending on diff --git a/hledger-lib/Hledger/Reports/ReportOptions.hs b/hledger-lib/Hledger/Reports/ReportOptions.hs index 8e1a46164..665829c0d 100644 --- a/hledger-lib/Hledger/Reports/ReportOptions.hs +++ b/hledger-lib/Hledger/Reports/ReportOptions.hs @@ -696,7 +696,7 @@ reportSpanHelper bothdates j ReportSpec{_rsQuery=query, _rsReportOpts=ropts} = _ -> Nothing -- If the requested span is open-ended, close it using the journal's start and end dates. -- This can still be the null (open) span if the journal is empty. - requestedspan' = dbg3 "requestedspan'" $ requestedspan `spanDefaultsFrom` (journalspan `spanUnion` pricespan) + requestedspan' = dbg3 "requestedspan'" $ requestedspan `spanDefaultsFrom` (journalspan `spanExtend` pricespan) -- The list of interval spans enclosing the requested span. -- This list can be empty if the journal was empty, -- or if hledger-ui has added its special date:-tomorrow to the query diff --git a/hledger/hledger.m4.md b/hledger/hledger.m4.md index dcf6b0602..c8cccc411 100644 --- a/hledger/hledger.m4.md +++ b/hledger/hledger.m4.md @@ -5050,8 +5050,6 @@ This allows one to combine queries using `AND`, `OR`, and `NOT`. `expr:"expenses:food OR (tag:A expenses:drink)"` -(But `OR` may not be reliable currently, [#2177](https://github.com/simonmichael/hledger/issues/2177).) - ## Queries and command options Some queries can also be expressed as command-line options: diff --git a/hledger/test/query-expr.test b/hledger/test/query-expr.test index cf476351d..8b452a99c 100644 --- a/hledger/test/query-expr.test +++ b/hledger/test/query-expr.test @@ -146,3 +146,15 @@ $ hledger -f - print expr:"not (tag:transactiontag=B)" expenses:food >= + +# ** 11. Posting-based reports handle OR'd open-ended date periods properly. (#2177) +< +2023-12-26 2023 + (2023) 2023 + +2024-01-26 2024 + (2024) 2024 + +$ hledger -f- reg -w80 expr:'date:2023 or date:2024' +2023-12-26 2023 (2023) 2023 2023 +2024-01-26 2024 (2024) 2024 4047 From 8d9ce2abf9bfc868d9982ea89b07d733f3399e24 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Fri, 1 Mar 2024 18:13:30 -1000 Subject: [PATCH 29/41] ;just:push: allow custom poll interval argument --- Justfile | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Justfile b/Justfile index 02abd3d83..8dc4349f7 100644 --- a/Justfile +++ b/Justfile @@ -1288,9 +1288,9 @@ sccv: # ** Misc ------------------------------------------------------------ MISC: -# push to github CI, wait for tests to pass, then push to master -@push: - tools/push +# push to github CI, wait for tests to pass, refreshing every INTERVAL (default:10s), then push to master. +@push *INTERVAL: + tools/push {{ INTERVAL }} # run some tests to validate the development environment # check-setup: From 805fa67a285f52420842b2cac4426d70bedadc9b Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Fri, 1 Mar 2024 22:23:17 -1000 Subject: [PATCH 30/41] ;tools:buglist: improvements --- tools/buglist/index.html | 42 ++++++++++++++++++++-------------------- 1 file changed, 21 insertions(+), 21 deletions(-) diff --git a/tools/buglist/index.html b/tools/buglist/index.html index 9588fbfd8..ae3f3e14b 100644 --- a/tools/buglist/index.html +++ b/tools/buglist/index.html @@ -10,32 +10,32 @@ th { white-space: nowrap; } tr { border-top:thin solid #eee; vertical-align:top; } td { padding:0 1em; } - .tag { color:white; text-shadow: 2px 2px 2px black; font-size:small; padding:2px 8px 4px 6px; border-radius:1em; } + /* .tag { color:white; text-shadow: 2px 2px 2px black; font-size:small; padding:2px 8px 4px 6px; border-radius:1em; } + .paletag { color:black; font-weight:bold; font-size:small; padding:2px 8px 4px 6px; border-radius:1em; } */ + .tag { color:white; font-weight:bold; font-size:small; padding:2px 8px 4px 6px; border-radius:1em; } .paletag { color:black; font-weight:bold; font-size:small; padding:2px 8px 4px 6px; border-radius:1em; } -

hledger open bugs

-

- Currently our user pain score is - Impact (number of people affected, 1-5) * Severity (for those affected, 1-5) / 25. -
+

hledger open bugs by user pain (user joy when fixed)

+

+ Our user pain score is + impact (number of people affected, 1-5) * severity (for those affected, 1-5) / 25 * 10.
The possible scores are: -0.04 -0.08 -0.12 -0.16 -0.20 -0.24 -0.32 -0.36 -0.40 -0.48 -0.60 -0.64 -0.80 -1.00 -. + 0.4 + 0.8 + 1.2 + 1.6 + 2.0 + 2.4 + 3.2 + 3.6 + 4.0 + 4.8 + 6.0 + 6.4 + 8.0 +10.0

From 7e3b205309df21b192213ebd2005583774249457 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Fri, 1 Mar 2024 22:24:06 -1000 Subject: [PATCH 31/41] dev:web: give amounts in the sidebar the "amount" class also --- hledger-web/templates/balance-report.hamlet | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/hledger-web/templates/balance-report.hamlet b/hledger-web/templates/balance-report.hamlet index bd0b1879a..e430a8910 100644 --- a/hledger-web/templates/balance-report.hamlet +++ b/hledger-web/templates/balance-report.hamlet @@ -17,9 +17,9 @@ $forall (acct, adisplay, aindent, abal) <- items $if hasSubAccounts acct only - + ^{mixedAmountAsHtml abal} - + ^{mixedAmountAsHtml total} From bac71714548c3b05964bc4edfcd2922fab7db05d Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Fri, 1 Mar 2024 22:50:26 -1000 Subject: [PATCH 32/41] imp:web: show zero amounts with their commodity symbol(s?) [#2140] This was mainly to make the sidebar more informative, but also affects and hopefully helps, all amounts displayed elsewhere. --- hledger-web/Hledger/Web/Widget/Common.hs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/hledger-web/Hledger/Web/Widget/Common.hs b/hledger-web/Hledger/Web/Widget/Common.hs index 01ca30758..a71ffb664 100644 --- a/hledger-web/Hledger/Web/Widget/Common.hs +++ b/hledger-web/Hledger/Web/Widget/Common.hs @@ -95,7 +95,7 @@ accountOnlyQuery = ("inacctonly:" <>) . quoteIfSpaced mixedAmountAsHtml :: MixedAmount -> HtmlUrl a mixedAmountAsHtml b _ = - for_ (lines (showMixedAmountWithoutCost False b)) $ \t -> do + for_ (lines (showMixedAmountWith noCostFmt{displayZeroCommodity=True} b)) $ \t -> do H.span ! A.class_ c $ toHtml t H.br where From cb0b054df7d2c5466ecd4ebbd889f8e30460457e Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Fri, 1 Mar 2024 23:08:31 -1000 Subject: [PATCH 33/41] doc:web: mention -E flag, and cost hiding, and zero balances that aren't [#2140] --- hledger-web/hledger-web.m4.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/hledger-web/hledger-web.m4.md b/hledger-web/hledger-web.m4.md index a063c4321..aafea02d3 100644 --- a/hledger-web/hledger-web.m4.md +++ b/hledger-web/hledger-web.m4.md @@ -129,6 +129,12 @@ Query options and arguments may be used to set an initial filter, which although not shown in the UI, will restrict the data shown, in addition to any search query entered in the UI. +Note that hledger-web shows accounts with zero balances by default, like `hledger-ui` (and unlike `hledger`). +Using the `-E/--empty` flag at startup will hide them. + +If you see accounts which appear to have a zero balance, but cannot be hidden with `-E`: +these have a mixed-cost balance which looks like zero when costs are hidden. +Currently hledger-web does not show costs at all. ## General help options From bf7b00819b3ffdfcb04b3b657cd0fed97b675897 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Sat, 2 Mar 2024 07:31:42 -1000 Subject: [PATCH 34/41] ;just: tidy up --- Justfile | 448 +++++++++++++++++++++++++++---------------------------- 1 file changed, 218 insertions(+), 230 deletions(-) diff --git a/Justfile b/Justfile index 8dc4349f7..12fa7bdcf 100644 --- a/Justfile +++ b/Justfile @@ -246,55 +246,30 @@ BUILDFLAGS := '-rtsopts ' + WARNINGS + GHCLOWMEMFLAGS + CABALMACROSFLAGS + ' -DD TIME := "{{ shell date +'%Y%m%d%H%M' }}" MONTHYEAR := "{{ shell date +'%B %Y' }}" -# ** ghci ------------------------------------------------------------ -GHCI: +# ** Building ------------------------------------------------------------ +BUILDING: -# run ghci on hledger-lib + hledger -@ghci: - $STACKGHCI exec -- $GHCI $BUILDFLAGS hledger/Hledger/Cli.hs +# build the hledger package showing ghc codegen times/allocations +@buildtimes: + time ($STACK build hledger --force-dirty --ghc-options='-fforce-recomp -ddump-timings' 2>&1 | grep -E '\bCodeGen \[.*time=') -# run ghci on hledger-lib + hledger with profiling/call stack information -@ghci-prof: - stack build --profile hledger --only-dependencies - $STACKGHCI exec -- $GHCI $BUILDFLAGS -fexternal-interpreter -prof -fprof-auto hledger/Hledger/Cli.hs - -# # run ghci on hledger-lib + hledger + dev.hs script -# @ghci-dev: -# $STACKGHCI exec -- $GHCI $BUILDFLAGS -fno-warn-unused-imports -fno-warn-unused-binds dev.hs - -# run ghci on hledger-lib + hledger + hledger-ui -@ghci-ui: - $STACKGHCI exec -- $GHCI $BUILDFLAGS hledger-ui/Hledger/UI/Main.hs - -# run ghci on hledger-lib + hledger + hledger-web -@ghci-web: - $STACKGHCI exec -- $GHCI $BUILDFLAGS hledger-web/app/main.hs - -# run ghci on hledger-lib + hledger + hledger-web + hledger-web test suite -@ghci-web-test: - $STACKGHCI exec -- $GHCI $BUILDFLAGS hledger-web/test/test.hs - -# # better than stack exec ? -# # XXX does not see changes to files -# # run ghci on hledger-lib + test runner -# ghci-lib-test: -# $STACKGHCI ghci --ghc-options="\'-rtsopts {{ WARNINGS }} -ihledger-lib -DDEVELOPMENT -DVERSION=\"1.26.99\"\'" hledger-lib/test/unittest.hs -# run ghci on all the hledger -# ghci-all: -# $STACK exec -- $GHCI $BUILDFLAGS \ -# hledger-ui/Hledger/UI/Main.hs \ -# hledger-web/app/main.hs \ - -# run ghci on hledger-lib doctests -@ghci-doctest: - cd hledger-lib; $STACKGHCI ghci hledger-lib:test:doctest - -# run ghci on Shake.hs -@ghci-shake: - $STACK exec {{ SHAKEDEPS }} -- ghci Shake.hs - -# ** ghcid ------------------------------------------------------------ -GHCID: +# # build an unoptimised hledger at bin/hledger.EXT.unopt (default: git describe) +# build-unopt *EXT: +# #!/usr/bin/env bash +# ext={{ if EXT == '' { `git describe --tags` } else { EXT } }} +# exe="bin/hledger.$ext.unopt" +# $STACK --verbosity=error install --ghc-options=-O0 hledger --local-bin-path=bin +# mv bin/hledger "$exe" +# echo "$exe" +# # build hledger with profiling enabled at bin/hledgerprof +# hledgerprof: +# # $STACK --verbosity=error install --local-bin-path=bin hledger +# $STACK build --profile hledger +# # hledger-lib --ghc-options=-fprof-auto +# # @echo "to profile, use $STACK exec --profile -- hledger ..." +# # build "bin/hledgercov" for coverage reports (with ghc) +# hledgercov: +# $STACK ghc {{ MAIN }} -fhpc -o bin/hledgercov -outputdir .hledgercovobjs $BUILDFLAGS # run ghcid on hledger-lib + hledger @ghcid: @@ -349,7 +324,53 @@ SHAKEDEPS := '\ ghcid-shake: stack exec {{ SHAKEDEPS }} -- ghcid Shake.hs -# ** dev.hs script ------------------------------------------------------------ +# ** Testing ------------------------------------------------------------ +TESTING: + +# run ghci on hledger-lib + hledger +@ghci: + $STACKGHCI exec -- $GHCI $BUILDFLAGS hledger/Hledger/Cli.hs + +# run ghci on hledger-lib + hledger with profiling/call stack information +@ghci-prof: + stack build --profile hledger --only-dependencies + $STACKGHCI exec -- $GHCI $BUILDFLAGS -fexternal-interpreter -prof -fprof-auto hledger/Hledger/Cli.hs + +# # run ghci on hledger-lib + hledger + dev.hs script +# @ghci-dev: +# $STACKGHCI exec -- $GHCI $BUILDFLAGS -fno-warn-unused-imports -fno-warn-unused-binds dev.hs + +# run ghci on hledger-lib + hledger + hledger-ui +@ghci-ui: + $STACKGHCI exec -- $GHCI $BUILDFLAGS hledger-ui/Hledger/UI/Main.hs + +# run ghci on hledger-lib + hledger + hledger-web +@ghci-web: + $STACKGHCI exec -- $GHCI $BUILDFLAGS hledger-web/app/main.hs + +# run ghci on hledger-lib + hledger + hledger-web + hledger-web test suite +@ghci-web-test: + $STACKGHCI exec -- $GHCI $BUILDFLAGS hledger-web/test/test.hs + +# # better than stack exec ? +# # XXX does not see changes to files +# # run ghci on hledger-lib + test runner +# ghci-lib-test: +# $STACKGHCI ghci --ghc-options="\'-rtsopts {{ WARNINGS }} -ihledger-lib -DDEVELOPMENT -DVERSION=\"1.26.99\"\'" hledger-lib/test/unittest.hs +# run ghci on all the hledger +# ghci-all: +# $STACK exec -- $GHCI $BUILDFLAGS \ +# hledger-ui/Hledger/UI/Main.hs \ +# hledger-web/app/main.hs \ + +# run ghci on hledger-lib doctests +@ghci-doctest: + cd hledger-lib; $STACKGHCI ghci hledger-lib:test:doctest + +# run ghci on Shake.hs +@ghci-shake: + $STACK exec {{ SHAKEDEPS }} -- ghci Shake.hs + # # hledger-lib/Hledger/Read/TimeclockReaderPP.hs # # build the dev.hs script for quick experiments (with ghc) # dev: @@ -372,34 +393,6 @@ ghcid-shake: # curl -F "file=@devprof-hc.hp" -F "title='hledger parser'" http://heap.ezyang.com/upload # curl -F "file=@devprof-hr.hp" -F "title='hledger parser'" http://heap.ezyang.com/upload -# ** Building ------------------------------------------------------------ -BUILDING: - -# build the hledger package showing ghc codegen times/allocations -@buildtimes: - time ($STACK build hledger --force-dirty --ghc-options='-fforce-recomp -ddump-timings' 2>&1 | grep -E '\bCodeGen \[.*time=') - -# # build an unoptimised hledger at bin/hledger.EXT.unopt (default: git describe) -# build-unopt *EXT: -# #!/usr/bin/env bash -# ext={{ if EXT == '' { `git describe --tags` } else { EXT } }} -# exe="bin/hledger.$ext.unopt" -# $STACK --verbosity=error install --ghc-options=-O0 hledger --local-bin-path=bin -# mv bin/hledger "$exe" -# echo "$exe" -# # build hledger with profiling enabled at bin/hledgerprof -# hledgerprof: -# # $STACK --verbosity=error install --local-bin-path=bin hledger -# $STACK build --profile hledger -# # hledger-lib --ghc-options=-fprof-auto -# # @echo "to profile, use $STACK exec --profile -- hledger ..." -# # build "bin/hledgercov" for coverage reports (with ghc) -# hledgercov: -# $STACK ghc {{ MAIN }} -fhpc -o bin/hledgercov -outputdir .hledgercovobjs $BUILDFLAGS - -# ** Testing ------------------------------------------------------------ -TESTING: - # run tests that are reasonably quick (files, unit, functional) and benchmarks test: filestest functest @@ -492,6 +485,18 @@ ADDONEXTS := 'pl py rb sh hs lhs rkt exe com bat' mkdir hledger/test/addons/hledger-addondir chmod +x hledger/test/addons/hledger-* +# compare hledger's and ledger's balance report +compare-balance: + #!/usr/bin/env bash + for f in examples/1txns-1accts.journal \ + examples/10txns-10accts.journal \ + ; do \ + (export f=$f; \ + printf "\n-------------------------------------------------------------------------------\n"; \ + echo "comparing hledger -f $f balance and ledger -f $f balance --flat"; \ + difft --color=always --display side-by-side-show-both <(hledger -f $f balance) <(ledger -f $f balance --flat) ) | tail +2; \ + done + # generate a hlint report # hlinttest hlint: # hlint --hint=hlint --report=hlint.html {{ SOURCEFILES }} @@ -513,6 +518,52 @@ ADDONEXTS := 'pl py rb sh hs lhs rkt exe com bat' installtest: cd; {{ justfile_directory() }}/hledger-install/hledger-install.sh +# ** Installing ------------------------------------------------------------ +INSTALLING: + +# # copy the current ~/.local/bin/hledger to bin/old/hledger-VER +# @copy-as VER: +# cp ~/.local/bin/hledger bin/old/hledger-{{ VER }}; echo "bin/hledger-{{ VER }}" + +# stack install, then copy the hledger executables to bin/old/hledger*-VER +@installas VER: + $STACK install --local-bin-path bin/old + for e in hledger hledger-ui hledger-web ; do cp bin/old/$e bin/old/$e-{{ VER }}; echo "bin/$e-{{ VER }}"; done + +# # make must be GNU Make 4.3+ +# .PHONY: shellcompletions +# # update shell completions in hledger package +# shellcompletions: +# make -C hledger/shell-completion/ clean-all all + +# download a recent set of hledger versions from github releases to bin/hledger-VER +get-binaries: + for V in 1.32.2 1.31 1.30 1.29.2 1.28 1.27.1; do just get-binary $OS x64 $V; done + just symlink-binaries + +# download hledger version VER for OS (linux, mac windows) and ARCH (x64) from github releases to bin/hledger-VER +# On gnu/linux: can't interpolate GTAR here for some reason, and need the shebang line. +get-binary OS ARCH VER: + #!/usr/bin/env bash + cd bin && curl -Ls https://github.com/simonmichael/hledger/releases/download/{{ VER }}/hledger-{{ OS }}-{{ ARCH }}.zip | funzip | `type -P gtar || echo tar` xf - hledger --transform 's/$/-{{ VER }}/' + +# add easier symlinks for all the minor hledger releases downloaded by get-binaries. +symlink-binaries: + just symlink-binary 1.32.2 + just symlink-binary 1.29.2 + just symlink-binary 1.27.1 + +# add an easier symlink for this minor hledger release (hledger-1.29 -> hledger-1.29.2, etc.) +@symlink-binary MINORVER: + cd bin && ln -sf hledger-$MINORVER hledger-`echo $MINORVER | sed -E 's/\.[0-9]+$//'` + +# sym-link some directories required by hledger-web dev builds +symlink-web-dirs: + echo "#ln -sf hledger-web/config # disabled, causes makeinfo warnings" + ln -sf hledger-web/messages + ln -sf hledger-web/static + ln -sf hledger-web/templates + # ** Benchmarking ------------------------------------------------------------ BENCHMARKING: @@ -573,27 +624,6 @@ samplejournals: # can't use $GHC or {{GHC}} here for some reason OS := `ghc -ignore-dot-ghci -package-env - -e 'import System.Info' -e 'putStrLn $ case os of "darwin"->"mac"; "mingw32"->"windows"; "linux"->"linux"; _->"other"'` -# download a recent set of hledger versions from github releases to bin/hledger-VER -get-binaries: - for V in 1.32.2 1.31 1.30 1.29.2 1.28 1.27.1; do just get-binary $OS x64 $V; done - just symlink-binaries - -# download hledger version VER for OS (linux, mac windows) and ARCH (x64) from github releases to bin/hledger-VER -# On gnu/linux: can't interpolate GTAR here for some reason, and need the shebang line. -get-binary OS ARCH VER: - #!/usr/bin/env bash - cd bin && curl -Ls https://github.com/simonmichael/hledger/releases/download/{{ VER }}/hledger-{{ OS }}-{{ ARCH }}.zip | funzip | `type -P gtar || echo tar` xf - hledger --transform 's/$/-{{ VER }}/' - -# add easier symlinks for all the minor hledger releases downloaded by get-binaries. -symlink-binaries: - just symlink-binary 1.32.2 - just symlink-binary 1.29.2 - just symlink-binary 1.27.1 - -# add an easier symlink for this minor hledger release (hledger-1.29 -> hledger-1.29.2, etc.) -@symlink-binary MINORVER: - cd bin && ln -sf hledger-$MINORVER hledger-`echo $MINORVER | sed -E 's/\.[0-9]+$//'` - # tools/generatejournal.hs 3 5 5 --chinese > examples/chinese.journal # don't regenerate, keep the simple version # $ just --set BENCHEXES ledger,hledger bench @@ -602,20 +632,14 @@ symlink-binaries: printf "Running quick benchmarks (times are approximate, can be skewed):\n" which quickbench >/dev/null && quickbench {{ ARGS }} || echo "quickbench not installed (see bench.sh), skipping" -@bench-quick8: - quickbench -w hledger-1.23,hledger-1.24,hledger-1.25,hledger-1.26,hledger-1.28,hledger-1.29,hledger-21ad,ledger - -@bench-quick3: - quickbench -w hledger-1.26,hledger-21ad,ledger '_ -f examples/10ktxns-1kaccts.journal print' '_ -f examples/10ktxns-1kaccts.journal register' '_ -f examples/10ktxns-1kaccts.journal balance' - -@bench-gtime: - for args in '-f examples/10ktxns-1kaccts.journal print' '-f examples/100ktxns-1kaccts.journal register' '-f examples/100ktxns-1kaccts.journal balance'; do \ - echo; \ - for app in hledger-1.26 hledger-21ad ledger; do \ - echo; echo $app $args:; \ - gtime $app $args >/dev/null; \ - done; \ - done +# @bench-gtime: +# for args in '-f examples/10ktxns-1kaccts.journal print' '-f examples/100ktxns-1kaccts.journal register' '-f examples/100ktxns-1kaccts.journal balance'; do \ +# echo; \ +# for app in hledger-1.26 hledger-21ad ledger; do \ +# echo; echo $app $args:; \ +# gtime $app $args >/dev/null; \ +# done; \ +# done # show throughput at various data sizes with the given hledger executable (requires samplejournals) @bench-throughput EXE: @@ -633,27 +657,16 @@ symlink-binaries: stack build hledger stack exec -- just throughput hledger +# show throughput of recent hledger versions (requires samplejournals) @bench-throughput-recent: - for v in 1.25 1.28 1.29 1.32 21ad; do printf "\nhledger-$v:\n"; for i in `seq 1 3`; do hledger-$v -f examples/10ktxns-10kaccts.journal stats | grep throughput; done; done + for v in 1.25 1.28 1.29 1.32 1.32.3; do printf "\nhledger-$v:\n"; for i in `seq 1 3`; do hledger-$v -f examples/10ktxns-10kaccts.journal stats | grep throughput; done; done -@bench-balance-many-accts: - quickbench -w hledger-1.26,hledger-21ad,ledger -f bench-many-accts.sh -N2 - #quickbench -w hledger-1.25,hledger-1.28,hledger-1.29,hledger-1.30,hledger-1.31,hledger-1.32,hledger-21ad,ledger -f bench-many-accts.sh -N2 +# @bench-balance-many-accts: +# quickbench -w hledger-1.26,hledger-21ad,ledger -f bench-many-accts.sh -N2 +# #quickbench -w hledger-1.25,hledger-1.28,hledger-1.29,hledger-1.30,hledger-1.31,hledger-1.32,hledger-21ad,ledger -f bench-many-accts.sh -N2 -@bench-balance-many-txns: - quickbench -w hledger-21ad,ledger -f bench-many-txns.sh -N2 - -# examples/100txns-100accts.journal \ -compare-balance: - #!/usr/bin/env bash - for f in examples/1txns-1accts.journal \ - examples/10txns-10accts.journal \ - ; do \ - (export f=$f; \ - printf "\n-------------------------------------------------------------------------------\n"; \ - echo "comparing hledger -f $f balance and ledger -f $f balance --flat"; \ - difft --color=always --display side-by-side-show-both <(hledger -f $f balance) <(ledger -f $f balance --flat) ) | tail +2; \ - done +# @bench-balance-many-txns: +# quickbench -w hledger-21ad,ledger -f bench-many-txns.sh -N2 # samplejournals bench.sh # bench: samplejournals tests/bench.tests tools/simplebench \ @@ -832,95 +845,14 @@ haddock-open: # @(printf "\nbrowser will open in $(BROWSEDELAY)s (adjust BROWSE in Makefile if needed)...\n\n"; sleep $(BROWSEDELAY); $(BROWSE) $(LOCALSITEURL)) & # @$(WATCHEXEC) --print-events -e md,m4 -i hledger.md -i hledger-ui.md -i hledger-web.md -r './Shake webmanuals && ./Shake orgfiles && make -sC site serve' -# ** Installing ------------------------------------------------------------ -INSTALLING: - -# # copy the current ~/.local/bin/hledger to bin/old/hledger-VER -# @copy-as VER: -# cp ~/.local/bin/hledger bin/old/hledger-{{ VER }}; echo "bin/hledger-{{ VER }}" - -# stack install, then copy the hledger executables to bin/old/hledger*-VER -@installas VER: - $STACK install --local-bin-path bin/old - for e in hledger hledger-ui hledger-web ; do cp bin/old/$e bin/old/$e-{{ VER }}; echo "bin/$e-{{ VER }}"; done - -# # make must be GNU Make 4.3+ -# .PHONY: shellcompletions -# # update shell completions in hledger package -# shellcompletions: -# make -C hledger/shell-completion/ clean-all all - -# ** Releasing ------------------------------------------------------------ -RELEASING: - -# Symlink/copy important files temporarily in .relfiles/. -relfiles: - #!/usr/bin/env bash - echo "linking/copying important release files in .relfiles/ for convenient access..." - mkdir -p .relfiles - cd .relfiles - for f in \ - ../stack.yaml \ - ../Shake.hs \ - ../hledger-install/hledger-install.sh \ - ../CHANGES.md \ - ../hledger/CHANGES.md \ - ../hledger-ui/CHANGES.md \ - ../hledger-web/CHANGES.md \ - ../hledger-lib/CHANGES.md \ - ../doc/github-release.md \ - ../doc/ANNOUNCE \ - ../doc/ANNOUNCE.masto \ - ../site/src/release-notes.md \ - ../site/src/install.md \ - ; do ln -sf $f .; done - cp ../doc/RELEASING.md ./RELEASING2.md # temp copy which can be edited without disruption - -# Prepare to release today, creating/switching to release branch, updating versions, dates, manuals, changelogs etc. -relprep VER: - #!/usr/bin/env bash - set -euo pipefail - [[ -z {{ VER }} ]] && usage - BRANCH=$(just _versionReleaseBranch {{ VER }}) - COMMIT="-c" - echo "Switching to $BRANCH, auto-creating it if needed..." - just _gitSwitchAutoCreate "$BRANCH" - echo "Bumping all version strings to {{ VER }} ..." - ./Shake setversion {{ VER }} $COMMIT - echo "Updating all command help texts for embedding..." - ./Shake cmdhelp $COMMIT - echo "Updating all dates in man pages..." - ./Shake mandates - echo "Generating all the manuals in all formats...." - ./Shake manuals $COMMIT - echo "Updating CHANGES.md files with latest commits..." - ./Shake changelogs $COMMIT - -# Push the current branch to github to generate release binaries. -@relbin: - # assumes the github remote is named "github" - git push -f github HEAD:binaries - -# Show last release date (of hledger package). -@reldate: - awk '/^#+ +[0-9]+\.[0-9].*([0-9]{4}-[0-9]{2}-[0-9]{2})/{print $3;exit}' hledger/CHANGES.md - -# Show last release date and version (of hledger package). -@rel: - just rels | head -1 - -# Show all release dates and versions (of hledger package). -@rels: - awk '/^#+ +[0-9]+\.[0-9].*([0-9]{4}-[0-9]{2}-[0-9]{2})/{printf "%s %s\n",$3,$2}' hledger/CHANGES.md - # Convert DATEARG to an ISO date. It can be an ISO date, number of recent days, or nothing (meaning last release date). -@datearg *DATEARG: +@_datearg *DATEARG: echo {{ if DATEARG == '' { `just reldate` } else { if DATEARG =~ '^\d+$' { `dateadd $(date +%Y-%m-%d) -$DATEARG` } else { DATEARG } } }} # Show activity since (mostly) this date or days ago or last release. Eg: just log > log.org log *DATEARG: #!/usr/bin/env osh - DATE=`just datearg $DATEARG` + DATE=`just _datearg $DATEARG` printf "* Activity since $DATE:\n\n" printf "Last release: `just rel`\n\n" just chlog @@ -954,7 +886,7 @@ GITLG := "git log --format='%ad %h %s' --date=short" # Show commits in the three repos since this date or days ago or last release, briefly. commitlog *DATEARG: #!/usr/bin/env osh - DATE=`just datearg $DATEARG` + DATE=`just _datearg $DATEARG` printf "** hledger commits\n\n" {{ GITLG }} --since $DATE echo @@ -1037,16 +969,79 @@ bloglog: echo "** pta.o: https://plaintextaccounting.org/#`date +%Y`" echo -# Some evil works against this.. -# echo "open https://www.reddit.com/r/plaintextaccounting/new, copy links since $DAYS days ago ($DATE), paste into obsidian, select, cut, and paste here for cleaning (in emacs shell use C-c C-d, C-c C-r)" -# just redditclean > $$.tmp -# printf "\n\n\n\n\n" -# cat $$.tmp -# rm -f $$.tmp -# -# Clean links copied from old.reddit.com. -@redditclean: - rg '^(\[.*?]\([^\)]+\)).*self.plaintextaccounting' -or '- $1\n' - +# # Some evil works against this.. +# # echo "open https://www.reddit.com/r/plaintextaccounting/new, copy links since $DAYS days ago ($DATE), paste into obsidian, select, cut, and paste here for cleaning (in emacs shell use C-c C-d, C-c C-r)" +# # just redditclean > $$.tmp +# # printf "\n\n\n\n\n" +# # cat $$.tmp +# # rm -f $$.tmp +# # +# # Clean links copied from old.reddit.com. +# @redditclean: +# rg '^(\[.*?]\([^\)]+\)).*self.plaintextaccounting' -or '- $1\n' - + +# ** Releasing ------------------------------------------------------------ +RELEASING: + +# Symlink/copy important files temporarily in .relfiles/. +relfiles: + #!/usr/bin/env bash + echo "linking/copying important release files in .relfiles/ for convenient access..." + mkdir -p .relfiles + cd .relfiles + for f in \ + ../stack.yaml \ + ../Shake.hs \ + ../hledger-install/hledger-install.sh \ + ../CHANGES.md \ + ../hledger/CHANGES.md \ + ../hledger-ui/CHANGES.md \ + ../hledger-web/CHANGES.md \ + ../hledger-lib/CHANGES.md \ + ../doc/github-release.md \ + ../doc/ANNOUNCE \ + ../doc/ANNOUNCE.masto \ + ../site/src/release-notes.md \ + ../site/src/install.md \ + ; do ln -sf $f .; done + cp ../doc/RELEASING.md ./RELEASING2.md # temp copy which can be edited without disruption + +# Prepare to release today, creating/switching to release branch, updating versions, dates, manuals, changelogs etc. +relprep VER: + #!/usr/bin/env bash + set -euo pipefail + [[ -z {{ VER }} ]] && usage + BRANCH=$(just _versionReleaseBranch {{ VER }}) + COMMIT="-c" + echo "Switching to $BRANCH, auto-creating it if needed..." + just _gitSwitchAutoCreate "$BRANCH" + echo "Bumping all version strings to {{ VER }} ..." + ./Shake setversion {{ VER }} $COMMIT + echo "Updating all command help texts for embedding..." + ./Shake cmdhelp $COMMIT + echo "Updating all dates in man pages..." + ./Shake mandates + echo "Generating all the manuals in all formats...." + ./Shake manuals $COMMIT + echo "Updating CHANGES.md files with latest commits..." + ./Shake changelogs $COMMIT + +# Push the current branch to github to generate release binaries. +@relbin: + # assumes the github remote is named "github" + git push -f github HEAD:binaries + +# Show last release date (of hledger package). +@reldate: + awk '/^#+ +[0-9]+\.[0-9].*([0-9]{4}-[0-9]{2}-[0-9]{2})/{print $3;exit}' hledger/CHANGES.md + +# Show last release date and version (of hledger package). +@rel: + just rels | head -1 + +# Show all release dates and versions (of hledger package). +@rels: + awk '/^#+ +[0-9]+\.[0-9].*([0-9]{4}-[0-9]{2}-[0-9]{2})/{printf "%s %s\n",$3,$2}' hledger/CHANGES.md # *** hledger version number helpers # (as hidden recipes, since just doesn't support global custom functions) @@ -1300,13 +1295,6 @@ MISC: # @({{ SHELLTEST }} checks \ # && echo $@ PASSED) || echo $@ FAILED -# sym-link some directories required by hledger-web dev builds -mkwebdirs: - echo "#ln -sf hledger-web/config # disabled, causes makeinfo warnings" - ln -sf hledger-web/messages - ln -sf hledger-web/static - ln -sf hledger-web/templates - # Show activity over the last N days (eg 7), for This Week In Hledger. @_lastweek DAYS: echo "hledger time last $DAYS days including today (this should be run on a Friday):" From 46b0c9bacf5becc6267d0b52ccffa4cb8a511c7d Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Sat, 2 Mar 2024 07:32:48 -1000 Subject: [PATCH 35/41] ;just: format --- Justfile | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/Justfile b/Justfile index 12fa7bdcf..dee6ed568 100644 --- a/Justfile +++ b/Justfile @@ -22,7 +22,7 @@ # (highlight-lines-matching-regexp "^@?\\w.*\\w:$" 'hi-pink) ; recipe headings (misses recipes with dependencies) # )) # -# This file is formatted by `just _fmt`, which currently eats blank lines a bit (and commits). +# This file is formatted by `just format`, which currently eats blank lines a bit (and commits). # # 'set export' makes constants and arguments available as $VAR as well as {{ VAR }}. # $ makes just code more like shell code. @@ -87,13 +87,14 @@ _watchgitdbg *WOPTS: BROWSE := 'open' # XXX These often don't work well interpolated as $CMD or {{ CMD }}, not sure why - # find GNU tools, eg on mac -GDATE := `type -P gdate || echo date` -GTAR := `type -P gtar || echo tar` -#GNUTAR := `which gtar >/dev/null && echo gtar || echo tar` +GDATE := `type -P gdate || echo date` +GTAR := `type -P gtar || echo tar` + +#GNUTAR := `which gtar >/dev/null && echo gtar || echo tar` # make ghc usable for scripting with -e + GHC := 'ghc -ignore-dot-ghci -package-env -' GHCI := 'ghci' @@ -204,8 +205,8 @@ DOCSOURCEFILES := ' CONTRIBUTING.md ' + MANUALSOURCEFILES + COMMANDHELPFILES TESTFILES := `fd '\.test$' --exclude ledger-compat` -# XXX it's fd-find on gnu/linux ? +# XXX it's fd-find on gnu/linux ? # # file(s) which require recompilation for a build to have an up-to-date version string # VERSIONSOURCEFILE := 'hledger/Hledger/Cli/Version.hs' # Two or three-part version string, set as program version in builds made by this makefile. @@ -542,6 +543,7 @@ get-binaries: just symlink-binaries # download hledger version VER for OS (linux, mac windows) and ARCH (x64) from github releases to bin/hledger-VER + # On gnu/linux: can't interpolate GTAR here for some reason, and need the shebang line. get-binary OS ARCH VER: #!/usr/bin/env bash @@ -622,6 +624,7 @@ samplejournals: # The current OS name, in the form used for hledger release binaries: linux, mac, windows or other. # can't use $GHC or {{GHC}} here for some reason + OS := `ghc -ignore-dot-ghci -package-env - -e 'import System.Info' -e 'putStrLn $ case os of "darwin"->"mac"; "mingw32"->"windows"; "linux"->"linux"; _->"other"'` # tools/generatejournal.hs 3 5 5 --chinese > examples/chinese.journal # don't regenerate, keep the simple version @@ -664,10 +667,8 @@ OS := `ghc -ignore-dot-ghci -package-env - -e 'import System.Info' -e 'putStrLn # @bench-balance-many-accts: # quickbench -w hledger-1.26,hledger-21ad,ledger -f bench-many-accts.sh -N2 # #quickbench -w hledger-1.25,hledger-1.28,hledger-1.29,hledger-1.30,hledger-1.31,hledger-1.32,hledger-21ad,ledger -f bench-many-accts.sh -N2 - # @bench-balance-many-txns: # quickbench -w hledger-21ad,ledger -f bench-many-txns.sh -N2 - # samplejournals bench.sh # bench: samplejournals tests/bench.tests tools/simplebench \ # $(call def-help,bench,\ @@ -687,7 +688,6 @@ OS := `ghc -ignore-dot-ghci -package-env - -e 'import System.Info' -e 'putStrLn # run progression benchmark tests and save graphical results\ # ) # tools/progressionbench -- -t png -k png - # # prof: samplejournals \ # # $(call def-help,prof,\ # # generate and archive an execution profile\ From a59df34a5b075f221271d503e689166bc897df3e Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Sat, 2 Mar 2024 07:36:43 -1000 Subject: [PATCH 36/41] ;just: cleanup --- Justfile | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/Justfile b/Justfile index dee6ed568..0291998fb 100644 --- a/Justfile +++ b/Justfile @@ -1,5 +1,5 @@ #!/usr/bin/env just -# * Project scripts, using https://github.com/casey/just (last tested with 1.16.0) +# * Project scripts, using https://github.com/casey/just (last tested with 1.24.0) # Usage: alias j=just, run j to list available scripts. # # After many years with make and plain shell and haskell for @@ -758,12 +758,6 @@ DOCUMENTING: # see also Shake.hs # http://www.haskell.org/haddock/doc/html/invoking.html -# optimise and commit RELEASING value map diagram -@releasediag: - pngquant doc/HledgerReleaseValueMap.png -f -o doc/HledgerReleaseValueMap.png - git add doc/HledgerReleaseValueMap.png - git commit -m ';doc: RELEASING: update value map' -- doc/HledgerReleaseValueMap.png - STACKHADDOCK := 'time ' + STACK + ' --verbosity=error haddock --fast --no-keep-going \ --only-locals --no-haddock-deps --no-haddock-hyperlink-source \ --haddock-arguments="--no-warnings" \ @@ -845,6 +839,12 @@ haddock-open: # @(printf "\nbrowser will open in $(BROWSEDELAY)s (adjust BROWSE in Makefile if needed)...\n\n"; sleep $(BROWSEDELAY); $(BROWSE) $(LOCALSITEURL)) & # @$(WATCHEXEC) --print-events -e md,m4 -i hledger.md -i hledger-ui.md -i hledger-web.md -r './Shake webmanuals && ./Shake orgfiles && make -sC site serve' +# optimise and commit RELEASING value map diagram +@releasediag: + pngquant doc/HledgerReleaseValueMap.png -f -o doc/HledgerReleaseValueMap.png + git add doc/HledgerReleaseValueMap.png + git commit -m ';doc: RELEASING: update value map' -- doc/HledgerReleaseValueMap.png + # Convert DATEARG to an ISO date. It can be an ISO date, number of recent days, or nothing (meaning last release date). @_datearg *DATEARG: echo {{ if DATEARG == '' { `just reldate` } else { if DATEARG =~ '^\d+$' { `dateadd $(date +%Y-%m-%d) -$DATEARG` } else { DATEARG } } }} From 63938f1da1b07305f808259d79f9100e88d9c362 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Sat, 2 Mar 2024 07:41:02 -1000 Subject: [PATCH 37/41] ;just:format: be silent if there's no changes to commit --- Justfile | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Justfile b/Justfile index 0291998fb..822efc51c 100644 --- a/Justfile +++ b/Justfile @@ -59,9 +59,9 @@ alias h := help @check: just --fmt --unstable --check -# if this justfile is error free but in non-standard format, reformat and commit it +# if this justfile is error free but in non-standard format, reformat it, and if it has changes, commit it @format: - just -q chk || just --fmt --unstable && git commit -m ';just: format' -- {{ justfile() }} + just -q chk || just -q --fmt --unstable && git diff --quiet || git commit -m ';just: format' -- {{ justfile() }} # rerun RECIPE when any watched-by-default file changes watch RECIPE *JOPTS: From ee0c36dfde02739eb23b53eef5bf88d13b8b9098 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Sat, 2 Mar 2024 10:06:35 -1000 Subject: [PATCH 38/41] ;tools: bump snapshot/ghc versions --- Shake.hs | 2 +- tools/changelog.hs | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/Shake.hs b/Shake.hs index 28db69032..1c4d99a6c 100755 --- a/Shake.hs +++ b/Shake.hs @@ -1,5 +1,5 @@ #!/usr/bin/env stack -{- stack script --resolver nightly-2023-10-13 --compile +{- stack script --resolver nightly-2024-02-28 --compile --extra-include-dirs /Library/Developer/CommandLineTools/SDKs/MacOSX12.1.sdk/usr/include/ffi --package base-prelude --package directory diff --git a/tools/changelog.hs b/tools/changelog.hs index 2c8164703..c8ed70427 100755 --- a/tools/changelog.hs +++ b/tools/changelog.hs @@ -1,5 +1,5 @@ #!/usr/bin/env stack -{- stack script --resolver lts-18.18 +{- stack script --resolver lts-22.12 --package data-default --package extra --package process From b605b5bfd591cd58b7d17367d97f8fe8e4d98a08 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Sat, 2 Mar 2024 11:50:10 -1000 Subject: [PATCH 39/41] ;doc:manuals: fix some code block language types --- hledger-ui/hledger-ui.m4.md | 2 ++ hledger/Hledger/Cli/Commands/Add.md | 4 ++-- hledger/Hledger/Cli/Commands/Roi.md | 6 +++--- hledger/hledger.m4.md | 28 +++++++++++++++------------- 4 files changed, 22 insertions(+), 18 deletions(-) diff --git a/hledger-ui/hledger-ui.m4.md b/hledger-ui/hledger-ui.m4.md index 587b7e665..574fdb3ce 100644 --- a/hledger-ui/hledger-ui.m4.md +++ b/hledger-ui/hledger-ui.m4.md @@ -341,9 +341,11 @@ This is very useful when reconciling. A good workflow is to have your bank's online register open in a browser window, for reference; the journal file open in an editor window; and hledger-ui in watch mode in a terminal window, eg: + ```cli $ hledger-ui --watch --register checking -C ``` + As you mark things cleared in the editor, you can see the effect immediately without having to context switch. This leaves more mental bandwidth for your accounting. diff --git a/hledger/Hledger/Cli/Commands/Add.md b/hledger/Hledger/Cli/Commands/Add.md index 1405e98bc..c30c150cd 100644 --- a/hledger/Hledger/Cli/Commands/Add.md +++ b/hledger/Hledger/Cli/Commands/Add.md @@ -33,9 +33,9 @@ Features: - If you make a mistake, enter `<` at any prompt to go one step backward. - Input prompts are displayed in a different colour when the terminal supports it. -Example (see https://hledger.org/add.html for a detailed tutorial): +Example (see for a detailed tutorial): -``` shell +```cli $ hledger add Adding transactions to journal file /src/hledger/examples/sample.journal Any command line arguments will be used as defaults. diff --git a/hledger/Hledger/Cli/Commands/Roi.md b/hledger/Hledger/Cli/Commands/Roi.md index 915cc682c..73357991d 100644 --- a/hledger/Hledger/Cli/Commands/Roi.md +++ b/hledger/Hledger/Cli/Commands/Roi.md @@ -72,7 +72,7 @@ contributions and which is due to the return on investment. assets, or otherwise converting between your investment commodity and any other commodity. Example: - ``` + ```journal 2019-01-01 Investing in Snake Oil assets:cash -$100 investment:snake oil @@ -84,7 +84,7 @@ any other commodity. Example: - "Profit and loss" is change in the value of your investment: - ``` + ```journal 2019-06-01 Snake Oil falls in value investment:snake oil = $57 equity:unrealized profit or loss @@ -98,7 +98,7 @@ investment return. Example: if you use `--inv snake --pnl equity:unrealized`, then postings in the example below would be classifed as: -``` +```journal 2019-01-01 Snake Oil #1 assets:cash -$100 ; cash flow posting investment:snake oil ; investment posting diff --git a/hledger/hledger.m4.md b/hledger/hledger.m4.md index c8cccc411..fbad0dade 100644 --- a/hledger/hledger.m4.md +++ b/hledger/hledger.m4.md @@ -67,12 +67,14 @@ are some good choices (see ). To get started, run `hledger add` and follow the prompts, or save some entries like the above in `$HOME/.hledger.journal`, -then try commands like:\ -`hledger print -x`\ -`hledger aregister assets`\ -`hledger balance`\ -`hledger balancesheet`\ -`hledger incomestatement`.\ +then try commands like: +```cli +$ hledger print -x +$ hledger aregister assets +$ hledger balance +$ hledger balancesheet +$ hledger incomestatement +``` Run `hledger` to list the commands. See also the "Starting a journal file" and "Setting opening balances" sections in [PART 5: COMMON TASKS](#part-5-common-tasks). @@ -1884,7 +1886,7 @@ Here are some tips for working with account types. 5. Otherwise, it will have no type. - For troubleshooting, you can list accounts and their types with: - ``` + ```cli $ hledger accounts --types [ACCTPAT] [-DEPTH] [type:TYPECODES] ``` @@ -3177,14 +3179,14 @@ Note the two kinds of field names mentioned here, and used only in hledger CSV r you can optionally name the CSV columns for easy reference (since hledger doesn't yet automatically recognise column headings in a CSV file), by writing arbitrary names in a `fields` list, eg: - ```csv + ```rules fields When, What, Some_Id, Net, Total, Foo, Bar ``` 2. Special **hledger field names** (`HLEDGERFIELD` in these docs): you must set at least some of these to generate the hledger transaction from a CSV record, by writing them as the left hand side of a [field assignment](#field-assignment), eg: - ```csv + ```rules date %When code %Some_Id description %What @@ -3192,7 +3194,7 @@ Note the two kinds of field names mentioned here, and used only in hledger CSV r amount1 $ %Total ``` or directly in a [`fields` list](#fields-list): - ```csv + ```rules fields date, description, code, , amount1, Foo, Bar currency $ comment %Foo %Bar @@ -4207,7 +4209,7 @@ some number of hours to an account. Or if the session spans more than one day, it is split into several transactions, one for each day. For the above time log, `hledger print` generates these journal entries: -``` shell +```cli $ hledger -f t.timeclock print 2015-03-30 * optional description after 2 spaces ; optional comment, tags: (some account) 0.33h @@ -5216,7 +5218,7 @@ Here there are no ordinary transactions, so the forecasted transactions begin on Forecast transactions affect all reports, as you would expect. Eg: -```terminal +```cli $ hledger areg rent --forecast --today=2023/4/21 Transactions in expenses:rent and subaccounts: 2023-05-20 rent as:ba:checking $1000 $1000 @@ -5226,7 +5228,7 @@ Transactions in expenses:rent and subaccounts: 2023-09-20 rent as:ba:checking $1000 $5000 ``` -```terminal +```cli $ hledger bal -M expenses --forecast --today=2023/4/21 Balance changes in 2023-05-01..2023-09-30: From f20457e2afafb61bf0cfbf3d6715f7c901eab5f6 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Sat, 2 Mar 2024 11:53:51 -1000 Subject: [PATCH 40/41] ;doc:manuals: code block language type --- hledger/hledger.m4.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/hledger/hledger.m4.md b/hledger/hledger.m4.md index fbad0dade..f8834892d 100644 --- a/hledger/hledger.m4.md +++ b/hledger/hledger.m4.md @@ -4389,7 +4389,7 @@ Letters: 2023-11-01 work:adm ccecces ``` -```journal +```cli $ hledger -f a.timedot print 2023-11-01 (work:adm) 1 ; t:c From 861a57ebf3cb7067a812da06d81dc17e6ea244f0 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Sat, 2 Mar 2024 12:10:27 -1000 Subject: [PATCH 41/41] ;doc:code blocks: language types --- hledger/hledger.m4.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/hledger/hledger.m4.md b/hledger/hledger.m4.md index f8834892d..022ee615d 100644 --- a/hledger/hledger.m4.md +++ b/hledger/hledger.m4.md @@ -4239,7 +4239,7 @@ To generate time logs, ie to clock in and clock out, you could: and perhaps the extras in [ledgerutils.el](http://hub.darcs.net/simon/ledgertools/ledgerutils.el) - at the command line, use these bash aliases: - ```shell + ```cli alias ti="echo i `date '+%Y-%m-%d %H:%M:%S'` \$* >>$TIMELOG" alias to="echo o `date '+%Y-%m-%d %H:%M:%S'` >>$TIMELOG" ``` @@ -5183,7 +5183,7 @@ You can override it - eg to forecast farther into the future, or to force foreca assets:bank:checking expenses:rent $1000 ``` -```terminal +```cli $ hledger print --forecast --today=2023/4/21 2023-05-20 rent ; generated-transaction: ~ monthly from 2022-12-20