From 6868ab06a4071a18a5437e4d6d2fbb017511e23b Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Thu, 9 Jan 2025 21:04:12 -1000 Subject: [PATCH] imp:close: --migrate -> --clopen; more doc rewrites --- hledger/Hledger/Cli/Commands/Close.hs | 34 +++++---- hledger/Hledger/Cli/Commands/Close.md | 100 +++++++++++++++----------- hledger/test/close.test | 44 ++++++------ 3 files changed, 95 insertions(+), 83 deletions(-) diff --git a/hledger/Hledger/Cli/Commands/Close.hs b/hledger/Hledger/Cli/Commands/Close.hs index 0c0fa4108..206e59dce 100644 --- a/hledger/Hledger/Cli/Commands/Close.hs +++ b/hledger/Hledger/Cli/Commands/Close.hs @@ -33,18 +33,15 @@ defretainacct = "equity:retained earnings" closemode = hledgerCommandMode $(embedFileRelative "Hledger/Cli/Commands/Close.txt") - [flagOpt "" ["migrate"] (\s opts -> Right $ setopt "migrate" s opts) "NEW" ("show closing and opening transactions," - <> " for Asset and Liability accounts by default, tagged for easy matching." - <> " The tag's default value can be overridden by providing NEW." - ) - ,flagOpt "" ["close"] (\s opts -> Right $ setopt "close" s opts) "NEW" "(default) show a closing transaction" - ,flagOpt "" ["open"] (\s opts -> Right $ setopt "open" s opts) "NEW" "show an opening transaction" - ,flagOpt "" ["assign"] (\s opts -> Right $ setopt "assign" s opts) "NEW" "show opening balance assignments" - ,flagOpt "" ["assert"] (\s opts -> Right $ setopt "assert" s opts) "NEW" "show closing balance assertions" - ,flagOpt "" ["retain"] (\s opts -> Right $ setopt "retain" s opts) "NEW" "show a retain earnings transaction, for Revenue and Expense accounts by default" - ,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" + [flagOpt "" ["clopen"] (\s opts -> Right $ setopt "clopen" s opts) "TAGVAL" "show closing and opening balances transactions, for AL accounts by default" + ,flagOpt "" ["close"] (\s opts -> Right $ setopt "close" s opts) "TAGVAL" "show just a closing balances transaction" + ,flagOpt "" ["open"] (\s opts -> Right $ setopt "open" s opts) "TAGVAL" "show just an opening balances transaction" + ,flagOpt "" ["assert"] (\s opts -> Right $ setopt "assert" s opts) "TAGVAL" "show a balance assertions transaction" + ,flagOpt "" ["assign"] (\s opts -> Right $ setopt "assign" s opts) "TAGVAL" "show a balance assignments transaction" + ,flagOpt "" ["retain"] (\s opts -> Right $ setopt "retain" s opts) "TAGVAL" "show a retain earnings transaction, for RX accounts by default" + ,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 ["assertion-type"] (\s opts -> Right $ setopt "assertion-type" s opts) "TYPE" "=, ==, =* or ==*" ,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" @@ -57,17 +54,18 @@ closemode = hledgerCommandMode ++ -- keep supporting old flag names for compatibility [flagNone ["closing"] (setboolopt "close") "old spelling of --close" ,flagNone ["opening"] (setboolopt "open") "old spelling of --open" + ,flagNone ["migrate"] (setboolopt "clopen") "old spelling of --clopen" ,flagReq ["close-to"] (\s opts -> Right $ setopt "close-acct" s opts) "ACCT" "old spelling of --close-acct" ,flagReq ["open-from"] (\s opts -> Right $ setopt "open-acct" s opts) "ACCT" "old spelling of --open-acct" ] ) - ([], Just $ argsFlag "[--migrate|--close|--open|--assign|--assert|--retain] [ACCTQUERY]") + ([], Just $ argsFlag "[--close|--open|--clopen|--assign|--assert|--retain] [ACCTQUERY]") -- | The close command's mode (subcommand). -- The code depends on these spellings. -data CloseMode = Migrate | Close | Open | Assign | Assert | Retain deriving (Eq,Show,Read) +data CloseMode = Clopen | Close | Open | Assign | Assert | Retain deriving (Eq,Show,Read) --- | Pick the rightmost flag spelled like a CloseMode (--migrate, --close, --open, etc), or default to Close. +-- | Pick the rightmost flag spelled like a CloseMode (--clopen, --close, --open, etc), or default to Close. closeModeFromRawOpts :: RawOpts -> CloseMode closeModeFromRawOpts rawopts = lastDef Close $ collectopts (\(name,_) -> readMay (capitalise name)) rawopts @@ -147,7 +145,7 @@ close CliOpts{rawopts_=rawopts, reportspec_=rspec0} j = do -- the closing (balance-asserting or balance-zeroing) transaction mclosetxn - | mode_ `notElem` [Migrate, Close, Assert, Retain] = Nothing + | mode_ `notElem` [Clopen, Close, Assert, Retain] = Nothing | otherwise = Just nulltransaction{ tdate=closedate, tdescription=closedesc, tcomment=comment, tpostings=closeps } @@ -162,7 +160,7 @@ close CliOpts{rawopts_=rawopts, reportspec_=rspec0} j = do -- XXX some duplication | mode_ == Assert = [ posting{ - paccount = a + paccount = a ,pamount = mixedAmount $ precise b{aquantity=0, acost=Nothing} -- after each commodity's last posting, assert 0 balance (#1035) -- balance assertion amounts are unpriced (#824) @@ -210,7 +208,7 @@ close CliOpts{rawopts_=rawopts, reportspec_=rspec0} j = do -- the opening (balance-assigning or balance-unzeroing) transaction mopentxn - | mode_ `notElem` [Migrate, Open, Assign] = Nothing + | mode_ `notElem` [Clopen, Open, Assign] = Nothing | otherwise = Just nulltransaction{ tdate=opendate, tdescription=opendesc, tcomment=comment, tpostings=openps } diff --git a/hledger/Hledger/Cli/Commands/Close.md b/hledger/Hledger/Cli/Commands/Close.md index 47ae8d160..8e9a51a11 100644 --- a/hledger/Hledger/Cli/Commands/Close.md +++ b/hledger/Hledger/Cli/Commands/Close.md @@ -2,19 +2,19 @@ (equity) -`close` generates several kinds of "closing" and/or "opening" transactions, useful in certain situations, including -migrating balances to a new journal file, retaining earnings into equity, consolidating balances, or viewing lots. +`close` prints several kinds of "closing" and/or "opening" transactions, useful in various situations: +migrating balances to a new journal file, retaining earnings into equity, consolidating balances, viewing lot costs.. Like `print`, it prints valid journal entries. -You can append or copy these to your journal file(s) when you are happy with how they look. +You can copy these into your journal file(s) when you are happy with how they look. ```flags Flags: - --migrate[=NEW] show closing and opening transactions, for Asset + --close[=NEW] (default) show a closing transaction + --open[=NEW] show an opening transaction + --clopen[=NEW] show closing and opening transactions, for Asset and Liability accounts by default, tagged for easy matching. The tag's default value can be overridden by providing NEW. - --close[=NEW] (default) show a closing transaction - --open[=NEW] show an opening transaction --assign[=NEW] show opening balance assignments --assert[=NEW] show closing balance assertions --retain[=NEW] show a retain earnings transaction, for Revenue @@ -39,45 +39,59 @@ Flags: (can unbalance transactions) ``` -`close` currently has six modes, selected by a single mode flag: +`close` has six modes, selected by choosing one of the mode flags (`--close` is the default). +They all do much the same operation, but with different defaults, useful in different situations. -### close --migrate +### close --clopen -This is the most common mode. -It prints a "closing balances" transaction that zeroes out all Asset and Liability balances (by default), +This is useful if migrating balances to a new journal file at the start of a new year. +It prints a "closing balances" transaction that zeroes out account balances (Asset and Liability accounts, by default), and an opposite "opening balances" transaction that restores them again. -The balancing account will be `equity:opening/closing balances` (or another specified by `--close-acct` or `--open-acct`). +Typically, you would run +``` +hledger close --clopen -e NEWYEAR >> $LEDGER_FILE +``` +and then move the opening transaction from the old file to the new file +(and probably also update your LEDGER_FILE environment variable). -This is useful when migrating balances to a new journal file at the start of a new year. -Essentially, you run `hledger close --migrate=NEWYEAR -e NEWYEAR` -and then copy the closing transaction to the end of the old file -and the opening transaction to the start of the new file. -The opening transaction sets correct starting balances in the new file when it is used alone, -and the closing transaction keeps balances correct when you use both old and new files together, -by cancelling out the following opening transaction and preventing buildup of duplicated opening balances. -Think of the closing/opening pair as "moving the balances into the next file". +Why might you do this ? If your reports are fast, you may not need it. +But at some point you will probably want to partition your data by time, +for performance or data integrity or regulatory reasons. +A new file or set of files per year is common. +Then, having each file/fileset "bookended" with opening and closing balance transactions +will allow you to freely pick and choose which files to read - +just the current year, any past year, any sequence of years, or all of them - +while showing correct account balances in each case. +The earliest opening balances transaction sets correct starting balances, +and any later closing/opening pairs will harmlessly cancel each other out. -You can close a different set of accounts by providing a query. -Eg if you want to include equity, you can add `assets liabilities equity` or [`type:ALE`](hledger.md#account-types) arguments. -(The balancing account is always excluded.) -Revenues and expenses usually are not migrated to a new file directly; see `--retain` below. +The balances will be transferred to and from `equity:opening/closing balances` by default. +You can override this by using `--close-acct` and/or `--open-acct`. -The generated transactions will have a `clopen:` tag, with its value set to -`--migrate`'s `NEW` argument if any, for easier matching or exclusion. -When `NEW` is not specified, it will be inferred if possible by incrementing -a number (eg a year number) within the default journal's main file name. -The other modes behave similarly. +You can select a different set of accounts to close/open by providing an account query. +Eg to add Equity accounts, provide arguments like `assets liabilities equity` or `type:ALE`. +When migrating to a new file, you'll usually want to bring along the AL or ALE accounts, +but not the RX accounts (Revenue, Expense). + +The generated transactions will have a `clopen:` tag. +If the main journal's file name contains a number (eg a year number), +the tag's value will be that file name with the number incremented. +Or you can choose the tag value yourself, by using `--clopen=TAGVAL`. ### close --close -This prints just the closing balances transaction of `--migrate`. -It is the default behaviour if you specify no mode flag. -Using the customisation options below, you can move balances from any set of accounts to a different account. +This prints just the closing balances transaction of `--clopen`. +It is the default if you don't specify a mode. + +More customisation options are described below. +Among other things, you can use `close --close` to generate a transaction +moving the balances from any set of accounts, to a different account. +(If you need to move just a portion of the balance, see [hledger-move](https://hledger.org/scripts.html#hledger-move).) ### close --open -This prints just the opening balances transaction of `--migrate`. -It is similar to [Ledger's equity command](https://ledger-cli.org/doc/ledger3.html#The-equity-command). +This prints just the opening balances transaction of `--clopen`. +(It is similar to [Ledger's equity command](https://ledger-cli.org/doc/ledger3.html#The-equity-command).) ### close --assert @@ -92,21 +106,21 @@ Unlike balance assertions, assignments will post changes to balances as needed t This is another way to set starting balances when migrating to a new file, and it will set them correctly even in the presence of earlier files which do not have a closing balances transaction. However, it can hide errors, and disturb the accounting equation, -so `--migrate` is usually recommended [for now](https://github.com/simonmichael/hledger/issues/2151). +so `--clopen` is usually [recommended](https://github.com/simonmichael/hledger/issues/2151). ### close --retain -This is like `--close`, but with different defaults: -it prints a transaction that transfers Revenue and Expense balances to `equity:retained earnings` (and adds a `retain:` tag). +This is like `--close`, but it closes Revenue and Expense account balances by default. +They will be transferred to `equity:retained earnings`, or another account specified with `--close-acct`. +Revenues and expenses correspond to changes in equity. +They are categorised separately for reporting purposes, +but traditionally at the end of each accounting period, businesses consolidate them into equity, This is called "retaining earnings", or "closing the books". -Revenues and expenses are actually part of equity, kept separate temporarily for clarity; -once they have been seen and noted, at the end of each accounting period, -businesses normally consolidate them into equity, -In personal accounting, there's not much benefit from this, and most people don't do it. -One reason to do it is to help the `balancesheetequity` report show a zero total, -demonstrating that the accounting equation (A-L=E) is satisfied. +In personal accounting, there's not much reason to do this, and most people don't. +(One reason to do it is to help the `balancesheetequity` report show a zero total, +demonstrating that the accounting equation (A-L=E) is satisfied.) ### close customisation @@ -196,7 +210,7 @@ $ hledger -f 2022.journal is not:desc:'retain earnings' Close assets/liabilities on 2022-12-31 and re-open them on 2023-01-01: ```cli -$ hledger close --migrate -f 2022.journal -p 2022 +$ hledger close --clopen -f 2022.journal -p 2022 # copy/paste the closing transaction to the end of 2022.journal # copy/paste the opening transaction to the start of 2023.journal ``` diff --git a/hledger/test/close.test b/hledger/test/close.test index e39311c66..3e567e281 100644 --- a/hledger/test/close.test +++ b/hledger/test/close.test @@ -20,7 +20,7 @@ # ** 1. By default, closes ALE accounts, on the last day of the report period. $ hledger close -f- -e 2017 -2016-12-31 closing balances ; start: +2016-12-31 closing balances ; clopen: assets:bank $-80 = $0 assets:cash $-10 = $0 liabilities $-25 = $0 @@ -30,7 +30,7 @@ $ hledger close -f- -e 2017 # ** 2. With --close, likewise. $ hledger close -f- -e 2017 --close -2016-12-31 closing balances ; start: +2016-12-31 closing balances ; clopen: assets:bank $-80 = $0 assets:cash $-10 = $0 liabilities $-25 = $0 @@ -46,15 +46,15 @@ $ hledger close -f- -e 2017 --retain >=0 -# ** 4. With --migrate, opens and closes ALE. -$ hledger close -f- -p 2016 --migrate -2016-12-31 closing balances ; start: +# ** 4. With --clopen, opens and closes ALE. +$ hledger close -f- -p 2016 --clopen +2016-12-31 closing balances ; clopen: assets:bank $-80 = $0 assets:cash $-10 = $0 liabilities $-25 = $0 equity:opening/closing balances -2017-01-01 opening balances ; start: +2017-01-01 opening balances ; clopen: assets:bank $80 = $80 assets:cash $10 = $10 liabilities $25 = $25 @@ -64,7 +64,7 @@ $ hledger close -f- -p 2016 --migrate # ** 5. With --open, opens ALE. $ hledger close -f- -p 2016 --open -2017-01-01 opening balances ; start: +2017-01-01 opening balances ; clopen: assets:bank $80 = $80 assets:cash $10 = $10 liabilities $25 = $25 @@ -74,7 +74,7 @@ $ hledger close -f- -p 2016 --open # ** 6. -x makes all amounts explicit. $ hledger close -f- -p 2016 -x -2016-12-31 closing balances ; start: +2016-12-31 closing balances ; clopen: assets:bank $-80 = $0 assets:cash $-10 = $0 liabilities $-25 = $0 @@ -90,7 +90,7 @@ $ hledger close -f- -p 2016 -x equity $ hledger -f- close assets -p 2019 -x -2019-12-31 closing balances ; start: +2019-12-31 closing balances ; clopen: assets -2A = 0A equity:opening/closing balances 2A @@ -100,7 +100,7 @@ $ hledger -f- close assets -p 2019 -x # 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 -2019-12-31 closing balances ; start: +2019-12-31 closing balances ; clopen: assets -1A @ 1B assets -1A @ 1C = 0A equity:opening/closing balances 1A @ 1B @@ -119,7 +119,7 @@ $ hledger -f- close assets -p 2019 --show-costs -x (assets) 1A @ 2B $ hledger -f- close assets -p 2019 -x -2019-12-31 closing balances ; start: +2019-12-31 closing balances ; clopen: assets -2A = 0A equity:opening/closing balances 2A @@ -127,7 +127,7 @@ $ hledger -f- close assets -p 2019 -x # ** 10. The same with costs preserved. $ hledger -f- close assets -p 2019 --show-costs -x -2019-12-31 closing balances ; start: +2019-12-31 closing balances ; clopen: assets -1A @ 1B assets -1A @ 2B = 0A equity:opening/closing balances 1A @ 1B @@ -160,7 +160,7 @@ $ hledger -f- close assets -p 2019 --show-costs -x liabilities:employer $ hledger -f- close -p 2016 assets liabilities --show-costs -x -2016-12-31 closing balances ; start: +2016-12-31 closing balances ; clopen: assets:bank -5,733.00 EUR = 0.00 EUR liabilities:employer $-10,000.00 liabilities:employer $5,000.00 @ 0.93 EUR @@ -177,7 +177,7 @@ $ hledger -f- close -p 2016 assets liabilities --show-costs -x # (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 -2016-12-31 closing balances ; start: +2016-12-31 closing balances ; clopen: assets:bank -5,733.00 EUR = 0.00 EUR equity:opening/closing balances 5,733.00 EUR liabilities:employer $-10,000.00 @@ -206,7 +206,7 @@ commodity AAA 0.00000000 expenses:banking $0.1280810 $ hledger -f- close -p 2019 assets --show-costs -x -2019-12-31 closing balances ; start: +2019-12-31 closing balances ; clopen: assets:aaa AAA -510 = AAA 0 assets:usd $-49.50 assets:usd $49.3900010 @ AAA 10.3528243 = $0.0000000 @@ -218,7 +218,7 @@ $ hledger -f- close -p 2019 assets --show-costs -x # ** 14. The same, without costs and with --interleaved. $ hledger -f- close -p 2019 assets --interleaved -x -2019-12-31 closing balances ; start: +2019-12-31 closing balances ; clopen: assets:aaa AAA -510 = AAA 0 equity:opening/closing balances AAA 510 assets:usd $-0.1099990 = $0.0000000 @@ -245,12 +245,12 @@ commodity $1,000.00 2000-01-01 (assets:a) $1,000 @@ $1,000 -$ hledger -f- close --migrate --show-costs -e 2001 -2000-12-31 closing balances ; start: +$ hledger -f- close --clopen --show-costs -e 2001 +2000-12-31 closing balances ; clopen: assets:a $-1,000. @@ $1,000. = $0 equity:opening/closing balances -2001-01-01 opening balances ; start: +2001-01-01 opening balances ; clopen: assets:a $1,000. @@ $1,000. = $1,000. equity:opening/closing balances @@ -264,12 +264,12 @@ $ hledger -f- close --assert --show-costs -e 2001 >= # ** 19. close supports --round, like print. -$ hledger -f- close --migrate -e 2001 --round=hard -c '$1.0' -2000-12-31 closing balances ; start: +$ hledger -f- close --clopen -e 2001 --round=hard -c '$1.0' +2000-12-31 closing balances ; clopen: assets:a $-1000.0 = $0.0 equity:opening/closing balances -2001-01-01 opening balances ; start: +2001-01-01 opening balances ; clopen: assets:a $1000.0 = $1000.0 equity:opening/closing balances