slaesvuo/hledger
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

imp: close: more cleanup; add --close; always default to ALE (#2020)

Browse Source
This commit is contained in:
Simon Michael 2023-04-05 12:14:07 -10:00
parent 7695e409bf
commit 1d83e14392
3 changed files with 74 additions and 62 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

17
hledger/Hledger/Cli/Commands/Close.hs
View File

@ -29,16 +29,17 @@ defcloseacct = "equity:opening/closing balances"
closemode = hledgerCommandMode closemode = hledgerCommandMode
$(embedFileRelative "Hledger/Cli/Commands/Close.txt") $(embedFileRelative "Hledger/Cli/Commands/Close.txt")
[flagNone ["open"] (setboolopt "open") "show an opening transaction (for ALE accounts by default)" [flagNone ["close"] (setboolopt "close") "show a closing transaction (default)"
,flagNone ["migrate"] (setboolopt "migrate") "show both closing and opening transactions (for ALE accounts by default)" ,flagNone ["open"] (setboolopt "open") "show an opening transaction"
,flagNone ["retain"] (setboolopt "retain") "show a retain earnings transaction (for RX accounts by default)" ,flagNone ["migrate"] (setboolopt "migrate") "show both closing and opening transactions"
,flagNone ["show-costs"] (setboolopt "show-costs") "show balances with different costs separately" ,flagNone ["retain"] (setboolopt "retain") "show a retain earnings transaction (for RX accounts)"
,flagNone ["interleaved"] (setboolopt "interleaved") "show source and destination postings together"
,flagNone ["explicit","x"] (setboolopt "explicit") "show all amounts explicitly" ,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-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 ["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 opening transaction's source account"
,flagReq ["open-acct"] (\s opts -> Right $ setopt "open-acct" s opts) "ACCT" "set account to open from"
] ]
[generalflagsgroup1] [generalflagsgroup1]
(hiddenflags (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 "retain" rawopts -> (True, False, defretaindesc, undefined, defretainacct, Type [Revenue, Expense])
| boolopt "migrate" rawopts -> (True, True, defclosedesc, defopendesc, defcloseacct, Type [Asset, Liability, Equity]) | boolopt "migrate" rawopts -> (True, True, defclosedesc, defopendesc, defcloseacct, Type [Asset, Liability, Equity])
| boolopt "open" rawopts -> (False, True, undefined, 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 -- descriptions to use for the closing/opening transactions
closedesc = T.pack $ fromMaybe defclosedesc_ $ maybestringopt "close-desc" rawopts closedesc = T.pack $ fromMaybe defclosedesc_ $ maybestringopt "close-desc" rawopts

76
hledger/Hledger/Cli/Commands/Close.md
View File

@ -1,54 +1,62 @@
## close ## close
(equity) `close [--close | --open | --migrate | --retain] [ACCTQUERY]`
`close [--open | --migrate | --retain] [QUERY]` Generate transactions which transfer account balances to and/or from
another account (typically equity).
Transfer balances to and/or from another account (usually equity). This can be useful for migrating balances to a new journal file,
Useful for migrating balances to a new journal file,
or for merging earnings into equity at end of accounting period. or for merging earnings into equity at end of accounting period.
By default, it prints a "closing balances" transaction that zeroes out By default, it prints a transaction that zeroes out ALE accounts
all accounts, transferring their balances to `equity:opening/closing balances`. (asset, liability, equity accounts; this requires account types to be configured);
or if ACCTQUERY is provided, the accounts matched by that.
*(experimental)*
_FLAGS _FLAGS
This command is useful in several situations. This command has four main modes, corresponding to the most common use cases:
It 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 2. With `--open`, it prints an opposite "opening balances" transaction that restores
of asset, liability and most equity accounts. This is similar to Ledger's equity command, those balances from zero. This is similar to Ledger's equity command.
and could be useful for propagating balances to a new file.
With `--migrate`, it prints both the closing and opening transactions, 3. With `--migrate`, it prints both the closing and opening transactions.
for asset, liability and most equity accounts.
This is the preferred way to migrate balances to a new file: 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, run `hledger close --migrate`,
and the closing transaction should be added at the end of the old file. add the closing transaction at the end of the old file, and
Now, the files can be combined for multi-file reporting, without disturbing balances add the opening transaction at the start of the new file.
(because the redundant closing/opening transactions cancel each other out). 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 4. With `--retain`, it prints a "retain earnings" transaction that transfers
revenue and expense balances to `equity:retained earnings`. RX (revenue and expense) balances to `equity:retained earnings`.
Businesses traditionally do this at the end of each accounting period; 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 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 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 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 `QUERY` (an account query). - 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. By default just one destination/source posting will be used, with its amount left implicit.
With `--x/--explicit` the amount will be shown explicitly, With `--x/--explicit`, the amount will be shown explicitly,
and if it involves multiple commodities, a separate posting and if it involves multiple commodities, a separate posting will be generated for each of them
will be generated for each commodity. (similar to `print -x`).
With `--interleaved`, each equity posting is shown next to the With `--show-costs`, any amount costs are shown, with separate postings for each cost.
corresponding source/destination posting. 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. 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); 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". eg `-e 2022` means "close on 2022-12-31".
The opening date is always the day after the closing date. 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 ### close and balance assertions
Balance assertions will be generated, verifying that the accounts have been reset to zero Balance assertions will be generated, verifying that the accounts have been reset to zero

43
hledger/test/close.test
View File

@ -17,19 +17,29 @@
liabilities $25 liabilities $25
assets:cash 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 $ hledger close -f- -e 2017
2016-12-31 closing balances 2016-12-31 closing balances
assets:bank $-80 = $0 assets:bank $-80 = $0
assets:cash $-10 = $0 assets:cash $-10 = $0
equity:opening $120 = $0 equity:opening $120 = $0
expenses:sweets $-5 = $0
liabilities $-25 = $0 liabilities $-25 = $0
equity:opening/closing balances equity:opening/closing balances
>=0 >=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 $ hledger close -f- -e 2017 --retain
2016-12-31 retain earnings 2016-12-31 retain earnings
expenses:sweets $-5 = $0 expenses:sweets $-5 = $0
@ -37,7 +47,7 @@ $ hledger close -f- -e 2017 --retain
>=0 >=0
# 3. With --migrate, opens and closes ALE. # 4. With --migrate, opens and closes ALE.
$ hledger close -f- -p 2016 --migrate $ hledger close -f- -p 2016 --migrate
2016-12-31 closing balances 2016-12-31 closing balances
assets:bank $-80 = $0 assets:bank $-80 = $0
@ -55,7 +65,7 @@ $ hledger close -f- -p 2016 --migrate
>=0 >=0
# 4. With --open, opens ALE. # 5. With --open, opens ALE.
$ hledger close -f- -p 2016 --open $ hledger close -f- -p 2016 --open
2017-01-01 opening balances 2017-01-01 opening balances
assets:bank $80 = $80 assets:bank $80 = $80
@ -66,19 +76,18 @@ $ hledger close -f- -p 2016 --open
>=0 >=0
# 5. -x makes all amounts explicit. # 6. -x makes all amounts explicit.
$ hledger close -f- -p 2016 -x $ hledger close -f- -p 2016 -x
2016-12-31 closing balances 2016-12-31 closing balances
assets:bank $-80 = $0 assets:bank $-80 = $0
assets:cash $-10 = $0 assets:cash $-10 = $0
equity:opening $120 = $0 equity:opening $120 = $0
expenses:sweets $-5 = $0
liabilities $-25 = $0 liabilities $-25 = $0
equity:opening/closing balances 0 equity:opening/closing balances $-5
>=0 >=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 2019/01/01
assets 1A @ 1B assets 1A @ 1B
@ -92,7 +101,7 @@ $ hledger -f- close assets -p 2019 -x
>=0 >=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). # Only the last posting in each commodity gets a balance assertion (#1035).
# Balance assertion amounts do not have a price. # Balance assertion amounts do not have a price.
$ hledger -f- close assets -p 2019 --show-costs -x $ hledger -f- close assets -p 2019 --show-costs -x
@ -104,7 +113,7 @@ $ hledger -f- close assets -p 2019 --show-costs -x
>=0 >=0
# 8. Closing a multi-priced balance, slightly more complex # 9. Closing a multi-priced balance, slightly more complex
# (different price in each transaction). # (different price in each transaction).
# XXX account parentheses should be preserved here # XXX account parentheses should be preserved here
< <
@ -121,7 +130,7 @@ $ hledger -f- close assets -p 2019 -x
>=0 >=0
# 9. The same with costs preserved. # 10. The same with costs preserved.
$ hledger -f- close assets -p 2019 --show-costs -x $ hledger -f- close assets -p 2019 --show-costs -x
2019-12-31 closing balances 2019-12-31 closing balances
assets -1A @ 1B assets -1A @ 1B
@ -131,7 +140,7 @@ $ hledger -f- close assets -p 2019 --show-costs -x
>=0 >=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 # Decimal places specified by the amount display style should not be stripped
# even if they are zeros (#1137). # even if they are zeros (#1137).
< <
@ -169,7 +178,7 @@ $ hledger -f- close -p 2016 assets liabilities --show-costs -x
>=0 >=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 # (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.) # 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 $ 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 >=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 $0.00
commodity AAA 0.00000000 commodity AAA 0.00000000
@ -212,7 +221,7 @@ $ hledger -f- close -p 2019 assets --show-costs -x
>=0 >=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 $ hledger -f- close -p 2019 assets --interleaved -x
2019-12-31 closing balances 2019-12-31 closing balances
assets:aaa AAA -510.00000000 = AAA 0.00000000 assets:aaa AAA -510.00000000 = AAA 0.00000000
@ -222,7 +231,7 @@ $ hledger -f- close -p 2019 assets --interleaved -x
>=0 >=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 999999-12-31
(a) 1 (a) 1