From 1d83e14392ed42f4d52ba41fdfd66009107b6127 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Wed, 5 Apr 2023 12:14:07 -1000 Subject: [PATCH] imp: close: more cleanup; add --close; always default to ALE (#2020) --- hledger/Hledger/Cli/Commands/Close.hs | 17 +++--- hledger/Hledger/Cli/Commands/Close.md | 76 ++++++++++++++------------- hledger/test/close.test | 43 +++++++++------ 3 files changed, 74 insertions(+), 62 deletions(-) diff --git a/hledger/Hledger/Cli/Commands/Close.hs b/hledger/Hledger/Cli/Commands/Close.hs index 37586496f..744ef1ce6 100644 --- a/hledger/Hledger/Cli/Commands/Close.hs +++ b/hledger/Hledger/Cli/Commands/Close.hs @@ -29,16 +29,17 @@ defcloseacct = "equity:opening/closing balances" closemode = hledgerCommandMode $(embedFileRelative "Hledger/Cli/Commands/Close.txt") - [flagNone ["open"] (setboolopt "open") "show an opening transaction (for ALE accounts by default)" - ,flagNone ["migrate"] (setboolopt "migrate") "show both closing and opening transactions (for ALE accounts by default)" - ,flagNone ["retain"] (setboolopt "retain") "show a retain earnings transaction (for RX accounts by default)" - ,flagNone ["show-costs"] (setboolopt "show-costs") "show balances with different costs separately" - ,flagNone ["interleaved"] (setboolopt "interleaved") "show source and destination postings together" + [flagNone ["close"] (setboolopt "close") "show a closing transaction (default)" + ,flagNone ["open"] (setboolopt "open") "show an opening transaction" + ,flagNone ["migrate"] (setboolopt "migrate") "show both closing and opening transactions" + ,flagNone ["retain"] (setboolopt "retain") "show a retain earnings transaction (for RX accounts)" ,flagNone ["explicit","x"] (setboolopt "explicit") "show all amounts explicitly" + ,flagNone ["show-costs"] (setboolopt "show-costs") "show amounts with different costs separately" + ,flagNone ["interleaved"] (setboolopt "interleaved") "show source and destination postings together" ,flagReq ["close-desc"] (\s opts -> Right $ setopt "close-desc" s opts) "DESC" "set closing transaction's description" + ,flagReq ["close-acct"] (\s opts -> Right $ setopt "close-acct" s opts) "ACCT" "set closing transaction's destination account" ,flagReq ["open-desc"] (\s opts -> Right $ setopt "open-desc" s opts) "DESC" "set opening transaction's description" - ,flagReq ["close-acct"] (\s opts -> Right $ setopt "close-acct" s opts) "ACCT" "set account to close to" - ,flagReq ["open-acct"] (\s opts -> Right $ setopt "open-acct" s opts) "ACCT" "set account to open from" + ,flagReq ["open-acct"] (\s opts -> Right $ setopt "open-acct" s opts) "ACCT" "set opening transaction's source account" ] [generalflagsgroup1] (hiddenflags @@ -56,7 +57,7 @@ close copts@CliOpts{rawopts_=rawopts, reportspec_=rspec0} j = do | boolopt "retain" rawopts -> (True, False, defretaindesc, undefined, defretainacct, Type [Revenue, Expense]) | boolopt "migrate" rawopts -> (True, True, defclosedesc, defopendesc, defcloseacct, Type [Asset, Liability, Equity]) | boolopt "open" rawopts -> (False, True, undefined, defopendesc, defcloseacct, Type [Asset, Liability, Equity]) - | otherwise -> (True, False, defclosedesc, undefined, defcloseacct, Any) + | otherwise -> (True, False, defclosedesc, undefined, defcloseacct, Type [Asset, Liability, Equity]) -- descriptions to use for the closing/opening transactions closedesc = T.pack $ fromMaybe defclosedesc_ $ maybestringopt "close-desc" rawopts diff --git a/hledger/Hledger/Cli/Commands/Close.md b/hledger/Hledger/Cli/Commands/Close.md index f3b01941a..43b70642d 100644 --- a/hledger/Hledger/Cli/Commands/Close.md +++ b/hledger/Hledger/Cli/Commands/Close.md @@ -1,54 +1,62 @@ ## close -(equity) +`close [--close | --open | --migrate | --retain] [ACCTQUERY]` -`close [--open | --migrate | --retain] [QUERY]` - -Transfer balances to and/or from another account (usually equity). -Useful for migrating balances to a new journal file, +Generate transactions which transfer account balances to and/or from +another account (typically equity). +This can be useful for migrating balances to a new journal file, or for merging earnings into equity at end of accounting period. -By default, it prints a "closing balances" transaction that zeroes out -all accounts, transferring their balances to `equity:opening/closing balances`. +By default, it prints a transaction that zeroes out ALE accounts +(asset, liability, equity accounts; this requires account types to be configured); +or if ACCTQUERY is provided, the accounts matched by that. + +*(experimental)* _FLAGS -This command is useful in several situations. -It has four main modes, corresponding to the most common use cases: +This command has four main modes, corresponding to the most common use cases: -By default, it prints a "closing balances" transaction that zeroes out all accounts. +1. With `--close` (default), it prints a "closing balances" transaction +that zeroes out ALE (asset, liability, equity) accounts by default +(this requires [account types](hledger.md#account-types) to be inferred or declared); +or, the accounts matched by the provided ACCTQUERY arguments. -With `--open`, it instead prints an "opening balances" transaction that restores the balances -of asset, liability and most equity accounts. This is similar to Ledger's equity command, -and could be useful for propagating balances to a new file. +2. With `--open`, it prints an opposite "opening balances" transaction that restores +those balances from zero. This is similar to Ledger's equity command. -With `--migrate`, it prints both the closing and opening transactions, -for asset, liability and most equity accounts. +3. With `--migrate`, it prints both the closing and opening transactions. This is the preferred way to migrate balances to a new file: -the opening transaction should be inserted at the start of the new file, -and the closing transaction should be added at the end of the old file. -Now, the files can be combined for multi-file reporting, without disturbing balances -(because the redundant closing/opening transactions cancel each other out). +run `hledger close --migrate`, +add the closing transaction at the end of the old file, and +add the opening transaction at the start of the new file. +The matching closing/opening transactions cancel each other out, +preserving correct balances during multi-file reporting.1 -With `--retain`, it prints a "retain earnings" transaction that transfers -revenue and expense balances to `equity:retained earnings`. +4. With `--retain`, it prints a "retain earnings" transaction that transfers +RX (revenue and expense) balances to `equity:retained earnings`. Businesses traditionally do this at the end of each accounting period; it is less necessary with computer-based accounting, but it could still be useful -if you want to see the accounting equation A=L+E satisfied. +if you want to see the accounting equation (A=L+E) satisfied. -In all modes, those defaults can be overridden: +In all modes, the defaults can be overridden: - the transaction descriptions can be changed with `--close-desc=DESC` and `--open-desc=DESC` -- the account to transfer to/from can be changed with `--close-acct=ACCT` -- the accounts to be closed/opened can be changed with `QUERY` (an account query). +- the account to transfer to/from can be changed with `--close-acct=ACCT` and `--open-acct=ACCT` +- the accounts to be closed/opened can be changed with `ACCTQUERY` (account query arguments). -By default just one equity posting, with an implicit amount, will be used. -With `--x/--explicit` the amount will be shown explicitly, -and if it involves multiple commodities, a separate posting -will be generated for each commodity. +By default just one destination/source posting will be used, with its amount left implicit. +With `--x/--explicit`, the amount will be shown explicitly, +and if it involves multiple commodities, a separate posting will be generated for each of them +(similar to `print -x`). -With `--interleaved`, each equity posting is shown next to the -corresponding source/destination posting. +With `--show-costs`, any amount costs are shown, with separate postings for each cost. +This is currently the best way to view investment lots. +If you have many currency conversion or investment transactions, it can generate very large journal entries. + +With `--interleaved`, each individual transfer is shown with source +and destination postings next to each other. +This could be useful for troubleshooting. The default closing date is yesterday, or the journal's end date, whichever is later. You can change this by specifying a [report end date](#report-start--end-date); @@ -57,12 +65,6 @@ The last day of the report period will be the closing date; eg `-e 2022` means "close on 2022-12-31". The opening date is always the day after the closing date. -### close and costs - -With `--show-costs`, any amount costs are shown, with separate postings for each cost. -(This currently the best way to view investment assets, showing lots and cost bases.) -If you have many currency conversion or investment transactions, it can generate very large journal entries. - ### close and balance assertions Balance assertions will be generated, verifying that the accounts have been reset to zero diff --git a/hledger/test/close.test b/hledger/test/close.test index f7e89b937..fd6a687b9 100644 --- a/hledger/test/close.test +++ b/hledger/test/close.test @@ -17,19 +17,29 @@ liabilities $25 assets:cash -# 1. By default, closes all accounts, on the last day of the report period. +# 1. By default, closes ALE accounts, on the last day of the report period. $ hledger close -f- -e 2017 2016-12-31 closing balances assets:bank $-80 = $0 assets:cash $-10 = $0 equity:opening $120 = $0 - expenses:sweets $-5 = $0 liabilities $-25 = $0 equity:opening/closing balances >=0 -# 2. With --retain, closes RX. +# 2. With --close, likewise. +$ hledger close -f- -e 2017 --close +2016-12-31 closing balances + assets:bank $-80 = $0 + assets:cash $-10 = $0 + equity:opening $120 = $0 + liabilities $-25 = $0 + equity:opening/closing balances + +>=0 + +# 3. With --retain, closes RX accounts. $ hledger close -f- -e 2017 --retain 2016-12-31 retain earnings expenses:sweets $-5 = $0 @@ -37,7 +47,7 @@ $ hledger close -f- -e 2017 --retain >=0 -# 3. With --migrate, opens and closes ALE. +# 4. With --migrate, opens and closes ALE. $ hledger close -f- -p 2016 --migrate 2016-12-31 closing balances assets:bank $-80 = $0 @@ -55,7 +65,7 @@ $ hledger close -f- -p 2016 --migrate >=0 -# 4. With --open, opens ALE. +# 5. With --open, opens ALE. $ hledger close -f- -p 2016 --open 2017-01-01 opening balances assets:bank $80 = $80 @@ -66,19 +76,18 @@ $ hledger close -f- -p 2016 --open >=0 -# 5. -x makes all amounts explicit. +# 6. -x makes all amounts explicit. $ hledger close -f- -p 2016 -x 2016-12-31 closing balances assets:bank $-80 = $0 assets:cash $-10 = $0 equity:opening $120 = $0 - expenses:sweets $-5 = $0 liabilities $-25 = $0 - equity:opening/closing balances 0 + equity:opening/closing balances $-5 >=0 -# 6. Closing a multi-priced balance. By default the transaction prices are ignored. +# 7. Closing a multi-priced balance. By default the transaction prices are ignored. < 2019/01/01 assets 1A @ 1B @@ -92,7 +101,7 @@ $ hledger -f- close assets -p 2019 -x >=0 -# 7. With --show-costs, the transaction prices are preserved. +# 8. With --show-costs, the transaction prices are preserved. # Only the last posting in each commodity gets a balance assertion (#1035). # Balance assertion amounts do not have a price. $ hledger -f- close assets -p 2019 --show-costs -x @@ -104,7 +113,7 @@ $ hledger -f- close assets -p 2019 --show-costs -x >=0 -# 8. Closing a multi-priced balance, slightly more complex +# 9. Closing a multi-priced balance, slightly more complex # (different price in each transaction). # XXX account parentheses should be preserved here < @@ -121,7 +130,7 @@ $ hledger -f- close assets -p 2019 -x >=0 -# 9. The same with costs preserved. +# 10. The same with costs preserved. $ hledger -f- close assets -p 2019 --show-costs -x 2019-12-31 closing balances assets -1A @ 1B @@ -131,7 +140,7 @@ $ hledger -f- close assets -p 2019 --show-costs -x >=0 -# 10. Closing a multi-priced balance, a more complex example. +# 11. Closing a multi-priced balance, a more complex example. # Decimal places specified by the amount display style should not be stripped # even if they are zeros (#1137). < @@ -169,7 +178,7 @@ $ hledger -f- close -p 2016 assets liabilities --show-costs -x >=0 -# 11. With --interleaved, each transfer's postings are adjacent. +# 12. With --interleaved, each transfer's postings are adjacent. # (And balances with the same cost are not necessarily combined into # a single posting. Eg the 5734 EUR above is 5733 EUR and 1 EUR below.) $ hledger -f- close -p 2016 assets liabilities --interleaved --show-costs -x @@ -187,7 +196,7 @@ $ hledger -f- close -p 2016 assets liabilities --interleaved --show-costs -x >=0 -# 12. A tricky case where a closing posting was rounded and failed to balance (#1164) +# 13. A tricky case where a closing posting was rounded and failed to balance (#1164) < commodity $0.00 commodity AAA 0.00000000 @@ -212,7 +221,7 @@ $ hledger -f- close -p 2019 assets --show-costs -x >=0 -# 13. The same, without costs and with --interleaved. +# 14. The same, without costs and with --interleaved. $ hledger -f- close -p 2019 assets --interleaved -x 2019-12-31 closing balances assets:aaa AAA -510.00000000 = AAA 0.00000000 @@ -222,7 +231,7 @@ $ hledger -f- close -p 2019 assets --interleaved -x >=0 -# 14. "The default closing date is yesterday, or the journal's end date, whichever is later." +# 15. "The default closing date is yesterday, or the journal's end date, whichever is later." < 999999-12-31 (a) 1