diff --git a/hledger-lib/Hledger/Data/JournalChecks.hs b/hledger-lib/Hledger/Data/JournalChecks.hs index 3b10b85cd..0d6ec9081 100644 --- a/hledger-lib/Hledger/Data/JournalChecks.hs +++ b/hledger-lib/Hledger/Data/JournalChecks.hs @@ -200,7 +200,11 @@ journalCheckTags j = do -- | Tag names which have special significance to hledger. builtinTags = [ "type" -- declares an account's type - ,"t" -- generated by timedot letters notation + ,"t" -- declares the (user defined, single letter) type of a 15m unit of time parsed from timedot format + -- generated by close + ,"balances" -- balance assertions transaction + ,"retain" -- retain earnings transaction + ,"start" -- opening balances, closing balances or balance assignment transaction -- optionally generated on periodic transactions and auto postings ,"generated-transaction" ,"generated-posting" diff --git a/hledger/Hledger/Cli/Commands/Close.hs b/hledger/Hledger/Cli/Commands/Close.hs index 363934c5c..b7f2d2fdb 100644 --- a/hledger/Hledger/Cli/Commands/Close.hs +++ b/hledger/Hledger/Cli/Commands/Close.hs @@ -21,20 +21,25 @@ import Hledger import Hledger.Cli.CliOptions import Safe (lastDef, readMay) -defretaindesc = "retain earnings" defclosedesc = "closing balances" defopendesc = "opening balances" -defretainacct = "equity:retained earnings" +defretaindesc = "retain earnings" + defcloseacct = "equity:opening/closing balances" +defretainacct = "equity:retained earnings" closemode = hledgerCommandMode $(embedFileRelative "Hledger/Cli/Commands/Close.txt") - [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 ["assert"] (setboolopt "assert") "show closing balance assertions" - ,flagNone ["assign"] (setboolopt "assign") "show opening balance assignments (an alternative to closing/opening transactions)" - ,flagNone ["retain"] (setboolopt "retain") "show a retain earnings transaction (for RX accounts)" + [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," + <> " with NEW (eg a new year) as tag value." + ) + ,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" @@ -52,10 +57,11 @@ closemode = hledgerCommandMode ,flagReq ["open-from"] (\s opts -> Right $ setopt "open-acct" s opts) "ACCT" "old spelling of --open-acct" ] ) - ([], Just $ argsFlag "[--close | --open | --migrate | --retain] [ACCTQUERY]") + ([], Just $ argsFlag "[--migrate|--close|--open|--assign|--assert|--retain] [ACCTQUERY]") --- | The close command's mode. Really a subcommand. -data CloseMode = Migrate | Close | Open | Assert | Assign | Retain deriving (Eq,Show,Read,Enum) +-- | The close command's mode (subcommand). +-- The code depends on these spellings. +data CloseMode = Migrate | 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. closeModeFromRawOpts :: RawOpts -> CloseMode @@ -71,6 +77,16 @@ close copts@CliOpts{rawopts_=rawopts, reportspec_=rspec0} j = do closeacct = T.pack $ fromMaybe defcloseacct_ $ maybestringopt "close-acct" rawopts openacct = maybe closeacct T.pack $ maybestringopt "open-acct" rawopts + -- For easy matching and exclusion, a recognisable tag is added to all generated transactions, + -- with the mode flag's argument if any (NEW, eg a new year number) as its argument. + comment = T.pack $ if + | mode_ == Assert -> "balances:" <> flagval + | mode_ == Retain -> "retain:" <> flagval + | otherwise -> "start:" <> flagval + where + flagval = fromMaybe "" $ maybestringopt modeflag rawopts + where modeflag = lowercase $ show mode_ + ropts = (_rsReportOpts rspec0){balanceaccum_=Historical, accountlistmode_=ALFlat} rspec1 = setDefaultConversionOp NoConversionOp rspec0{_rsReportOpts=ropts} @@ -112,7 +128,9 @@ close copts@CliOpts{rawopts_=rawopts, reportspec_=rspec0} j = do -- the closing (balance-asserting or balance-zeroing) transaction mclosetxn | mode_ `notElem` [Migrate, Close, Assert, Retain] = Nothing - | otherwise = Just nulltransaction{tdate=closedate, tdescription=closedesc, tpostings=closeps} + | otherwise = Just nulltransaction{ + tdate=closedate, tdescription=closedesc, tcomment=comment, tpostings=closeps + } where closedesc = T.pack $ fromMaybe defclosedesc_ $ maybestringopt "close-desc" rawopts where defclosedesc_ = if mode_ == Retain then defretaindesc else defclosedesc @@ -169,7 +187,9 @@ close copts@CliOpts{rawopts_=rawopts, reportspec_=rspec0} j = do -- the opening (balance-assigning or balance-unzeroing) transaction mopentxn | mode_ `notElem` [Migrate, Open, Assign] = Nothing - | otherwise = Just nulltransaction{tdate=opendate, tdescription=opendesc, tpostings=openps} + | otherwise = Just nulltransaction{ + tdate=opendate, tdescription=opendesc, tcomment=comment, tpostings=openps + } where opendesc = T.pack $ fromMaybe defopendesc $ maybestringopt "open-desc" rawopts openps diff --git a/hledger/Hledger/Cli/Commands/Close.md b/hledger/Hledger/Cli/Commands/Close.md index b224b9688..ab0f823cc 100644 --- a/hledger/Hledger/Cli/Commands/Close.md +++ b/hledger/Hledger/Cli/Commands/Close.md @@ -9,8 +9,6 @@ You can append or copy these to your journal file(s) when you are happy with how _FLAGS - - `close` currently has six modes, selected by a single mode flag: ### close --migrate @@ -21,7 +19,7 @@ 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`). This is useful when migrating balances to a new journal file at the start of a new year. -Essentially, you run `hledger close --migrate -e NEWYEAR` +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, @@ -34,6 +32,11 @@ Eg if you want to include equity, you can add `assets liabilities equity` or [`t (The balancing account is always excluded.) Revenues and expenses usually are not migrated to a new file directly; see `--retain` below. +The generated transactions will have a `start:` tag, with its value set to +`--migrate`'s `NEW` argument if any, for easier matching or exclusion. +It's a good idea to provide a `NEW` argument, unique to the new file; the new year number is most often used. +The other modes behave similarly. + ### close --close This prints just the closing balances transaction of `--migrate`. @@ -47,8 +50,8 @@ It is similar to [Ledger's equity command](https://ledger-cli.org/doc/ledger3.ht ### close --assert -This prints a "closing balances" transaction that just declares [balance assertions](#balance-assertions) -for the current balances without changing them. +This prints a "closing balances" transaction (with `balances:` tag), +that just declares [balance assertions](#balance-assertions) for the current balances without changing them. It could be useful as documention and to guard against changes. ### close --assign @@ -64,7 +67,8 @@ So `--migrate` is generally the best way to set to set balances in new files, [f ### close --retain This is like `--close` with different defaults: -it prints a "retain earnings" transaction that transfers revenue and expense balances to `equity:retained earnings`. +it prints a "retain earnings" transaction (with `retain:` tag), +that transfers revenue and expense balances to `equity:retained earnings`. This is a different kind of closing, called "retaining earnings" or "closing the books"; it is traditionally performed by businesses at the end of each accounting period, @@ -81,6 +85,7 @@ In all modes, the following things can be overridden: - the accounts to be closed/opened, with account query arguments - the balancing account, with `--close-acct=ACCT` and/or `--open-acct=ACCT` - the transaction descriptions, with `--close-desc=DESC` and `--open-desc=DESC` +- the transaction's tag value, with a `--MODE=NEW` option argument - the closing/opening dates, with `-e OPENDATE` By default, the closing date is yesterday, or the journal's end date, whichever is later; diff --git a/hledger/hledger.m4.md b/hledger/hledger.m4.md index 97f280230..b2813f3d6 100644 --- a/hledger/hledger.m4.md +++ b/hledger/hledger.m4.md @@ -1619,6 +1619,9 @@ followed by a colon may work. The following tag names are generated by hledger or have special significance to hledger, so you may want to avoid using them yourself: +- `balances` -- a balance assertions transaction generated by close +- `retain` -- a retain earnings transaction generated by close +- `start` -- a opening balances, closing balances or balance assignment transaction generated by close - `generated-transaction` -- a transaction generated by --forecast - `generated-posting` -- a posting generated by --auto - `modified` -- a transaction which has had postings added by --auto diff --git a/hledger/test/close.test b/hledger/test/close.test index a553878f0..681f81619 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 +2016-12-31 closing balances ; start: 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 +2016-12-31 closing balances ; start: assets:bank $-80 = $0 assets:cash $-10 = $0 liabilities $-25 = $0 @@ -40,7 +40,7 @@ $ hledger close -f- -e 2017 --close # ** 3. With --retain, closes RX accounts. $ hledger close -f- -e 2017 --retain -2016-12-31 retain earnings +2016-12-31 retain earnings ; retain: expenses:sweets $-5 = $0 equity:retained earnings @@ -48,13 +48,13 @@ $ hledger close -f- -e 2017 --retain # ** 4. With --migrate, opens and closes ALE. $ hledger close -f- -p 2016 --migrate -2016-12-31 closing balances +2016-12-31 closing balances ; start: assets:bank $-80 = $0 assets:cash $-10 = $0 liabilities $-25 = $0 equity:opening/closing balances -2017-01-01 opening balances +2017-01-01 opening balances ; start: 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 +2017-01-01 opening balances ; start: 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 +2016-12-31 closing balances ; start: 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 +2019-12-31 closing balances ; start: 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 +2019-12-31 closing balances ; start: 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 +2019-12-31 closing balances ; start: 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 +2019-12-31 closing balances ; start: 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 +2016-12-31 closing balances ; start: 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 +2016-12-31 closing balances ; start: 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 +2019-12-31 closing balances ; start: 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 +2019-12-31 closing balances ; start: assets:aaa AAA -510 = AAA 0 equity:opening/closing balances AAA 510 assets:usd $-0.1099990 = $0.0000000