diff --git a/doc/lib.m4 b/doc/lib.m4 index 5cc170c87..de63b07dd 100644 --- a/doc/lib.m4 +++ b/doc/lib.m4 @@ -197,3 +197,6 @@ m4_define({{_LEDGER_FILE_}}, {{ The journal file path when not specified with `-f`. Default: `~/.hledger.journal` (on windows, perhaps `C:/Users/USER/.hledger.journal`). }} )m4_dnl +m4_dnl +m4_define({{_FLAGS_}}, {{}})m4_dnl +m4_dnl diff --git a/hledger/Hledger/Cli/CliOptions.hs b/hledger/Hledger/Cli/CliOptions.hs index 62ac89c02..d1bf427fd 100644 --- a/hledger/Hledger/Cli/CliOptions.hs +++ b/hledger/Hledger/Cli/CliOptions.hs @@ -226,27 +226,33 @@ quickAddonCommandMode name = (defCommandMode [name]) { } } --- | A template for a command's CLI help, influencing the content and layout --- of the usage text generated by a cmdargs mode. --- It is a multiline string structured like so: --- The first line defines the command name (first word) and aliases (any other words). --- From the second line up to a line containing just "FLAGS", or the end, is the preamble, --- displayed above the flags list generated by cmdargs. Short help goes here. --- Any lines after the FLAGS line are the postamble, displayed below the flags list. --- Long help/full manual goes here. +-- | A command's documentation. Used both as part of CLI help, and as +-- part of the hledger manual. See parseHelpTemplate. type HelpTemplate = String --- | Parse a help template into command names, help preamble, and help postamble lines. +-- | Parse a command's documentation, as follows: +-- +-- - First line: the command name then any aliases, as one or more space or comma-separated words +-- +-- - Second line to a line containing just _FLAGS_, or the end: the short help +-- +-- - Any lines after _FLAGS_: the long help (split into lines for cmdargs) +-- +-- The CLI help displays the short help, then the cmdargs-generated +-- flags list, then the long help (which some day we might make +-- optional again). The manual displays the short help followed by +-- the long help, with no flags list. +-- parseHelpTemplate :: HelpTemplate -> Maybe ([Name], String, [String]) parseHelpTemplate t = case lines t of [] -> Nothing - (l:ls) -> Just (names, preamble, postamblelines) + (l:ls) -> Just (names, shorthelp, longhelplines) where - names = words l - (preamblels, postamblels) = break (== "FLAGS") ls - preamble = unlines $ reverse $ dropWhile null $ reverse preamblels - postamblelines = dropWhile null $ drop 1 postamblels + names = words $ map (\c -> if c==',' then ' ' else c) l + (shorthelpls, longhelpls) = break (== "_FLAGS_") ls + shorthelp = unlines $ reverse $ dropWhile null $ reverse shorthelpls + longhelplines = dropWhile null $ drop 1 longhelpls -- | Build a cmdarg mode for a hledger command, -- from a help template and flag/argument specifications. @@ -257,11 +263,11 @@ hledgerCommandMode :: HelpTemplate -> [Flag RawOpts] -> [(Help, [Flag RawOpts])] hledgerCommandMode tmpl ungroupedflags groupedflags hiddenflags args = case parseHelpTemplate tmpl of Nothing -> error' $ "Could not parse help template:\n"++tmpl++"\n" - Just (names, preamble, postamblelines) -> + Just (names, shorthelp, longhelplines) -> (defCommandMode names) { - modeHelp = preamble - ,modeHelpSuffix = postamblelines - ,modeGroupFlags = Group { + modeHelp = shorthelp + ,modeHelpSuffix = longhelplines + ,modeGroupFlags = Group { groupUnnamed = ungroupedflags ,groupNamed = groupedflags ,groupHidden = hiddenflags diff --git a/hledger/Hledger/Cli/Commands/Close.hs b/hledger/Hledger/Cli/Commands/Close.hs index 4f92e5bd5..6572d2815 100755 --- a/hledger/Hledger/Cli/Commands/Close.hs +++ b/hledger/Hledger/Cli/Commands/Close.hs @@ -16,56 +16,7 @@ import Hledger.Cli.CliOptions import System.Console.CmdArgs.Explicit as C closemode = hledgerCommandMode - [here| close equity -Print a "closing balances" transaction that brings all accounts (or with -query arguments, just the matched accounts) to a zero (historical) balance, -followed by an opposite "opening balances" transaction that restores the -balances from zero. - -FLAGS - -The opening transaction is useful to carry over asset/liability balances -if you choose to start a new journal file, eg yearly. The closing transaction -can be a useful complement, allowing you to optionally include old files -(for more history) without disturbing the asset/liability balances -(since the closing/opening pairs cancel out). - -This command may also be useful for closing out expense/income accounts -for a period (ie "closing the books" in accounting). - -Both transactions include balance assertions for the closed/reopened accounts. - -You probably shouldn't use status or realness queries (eg -C or -R) with this -command, or the balance assertions will require that query to pass. -Likewise, if you generate them with --auto, the assertions will depend on -any auto postings and --auto will be required to make them pass. - -By default, the closing transaction is dated yesterday, with balances -calculated as of end of yesterday, and the opening transaction is dated today. -To close on some other date, use: `hledger close -e OPENINGDATE ...`. -(-p or date: can also be used, the begin date is ignored.) - -You can chose to print just one of the transactions with `--opening` -or `--closing`. - -For example, carrying asset/liability balances into a new file for 2018: -``` -$ hledger close -f 2017.journal -e 2018/1/1 ^assets ^liab >>2017.journal -# cut & paste the opening transaction from 2017.journal to a new 2018.journal -# now: -$ hledger bs -f 2018.journal # correct balances -$ hledger bs -f 2018.journal -f 2017.journal # still correct -$ hledger bs -f 2017.journal not:desc:closing # must exclude closing txn -``` - -Transactions spanning the closing date may complicate matters. Eg, if -closing at end of 2017: -``` -2017/12/31 - expenses:food 1 - assets:bank:checking -1 ; date:2018/1/1 -``` - |] + [hereFile|hledger/Hledger/Cli/Commands/Close.md|] [flagNone ["opening"] (\opts -> setboolopt "opening" opts) "show just opening transaction" ,flagNone ["closing"] (\opts -> setboolopt "closing" opts) "show just closing transaction" ] diff --git a/hledger/Hledger/Cli/Commands/Close.md b/hledger/Hledger/Cli/Commands/Close.md new file mode 100644 index 000000000..0db83eb1b --- /dev/null +++ b/hledger/Hledger/Cli/Commands/Close.md @@ -0,0 +1,79 @@ +close, equity + +Prints a "closing balances" transaction and an "opening balances" transaction, +that bring account balances to and from zero, respectively. +Useful for, eg: + +- bringing asset/liability balances forward into a new journal file +- closing out revenues/expenses to retained earnings at the end of a period + +_FLAGS_ + +The closing transaction transfers balances to "equity:closing balances". +The opening transaction transfers balances from "equity:opening balances". +You can chose to print just one of the transactions by using the +`--opening` or `--closing` flag. + +If you split your journal files by time (eg yearly), you will +typically run this command at the end of the year, and save the +closing transaction as last entry of the old file, and the opening +transaction as the first entry of the new file. +This makes the files self contained, so that correct balances are +reported no matter which of them are loaded. Ie, if you load just one +file, the balances are initialised correctly; or if you load several +files, the redundant closing/opening transactions cancel each other +out. (They will show up in print or register reports; you can exclude +them with a query like `not:desc:'(opening|closing) balances'`.) + +If you're running a business, you might also use this command to +"close the books" at the end of an accounting period, transferring +income statement account balances to retained earnings. (You may want +to change the equity account name to something like +"equity:retained earnings" for clarity.) + +By default, the closing transaction is dated yesterday, the balances +are calculated as of end of yesterday, and the opening transaction is dated today. +To close on some other date, use: `hledger close -e OPENINGDATE`. +Eg, to close/open on the 2018/2019 boundary, use `-e 2019`. +You can also use -p or `date:PERIOD` (any starting date is ignored). + +Both transactions will include balance assertions for the +closed/reopened accounts. You probably shouldn't use status or +realness filters (like -C or -R or `status:`) with this command, or +the generated balance assertions will depend on these flags. +Likewise, if you run this command with --auto, the balance assertions +will probably always require --auto. + +Examples: + +Carrying asset/liability balances into a new file for 2019, all from command line. + +*Warning: we use `>>` here to append; be careful not to type a single `>` which would wipe your journal!* + + $ hledger close -f 2018.journal -e 2019 assets liabilities --opening >>2019.journal + $ hledger close -f 2018.journal -e 2019 assets liabilities --closing >>2018.journal + +Now: + + $ hledger bs -f 2019.journal # one file - balances are correct + $ hledger bs -f 2018.journal -f 2019.journal # two files - balances still correct + $ hledger bs -f 2018.journal not:desc:closing # to see year-end balances, must exclude closing txn + +Transactions spanning the closing date can complicate matters, breaking balance assertions: + + 2018/12/30 a purchase made in 2018, clearing the following year + expenses:food 5 + assets:bank:checking -5 ; [2019/1/2] + +Here's one way to resolve that: + + ; in 2018.journal: + 2018/12/30 a purchase made in 2018, clearing the following year + expenses:food 5 + liabilities:pending + + ; in 2019.journal: + 2019/1/2 clearance of last year's pending transactions + liabilities:pending 5 = 0 + assets:checking + diff --git a/hledger/Hledger/Cli/Commands/README b/hledger/Hledger/Cli/Commands/README new file mode 100644 index 000000000..a26a45899 --- /dev/null +++ b/hledger/Hledger/Cli/Commands/README @@ -0,0 +1,22 @@ +hledger's built-in commands. + +Each command has a similarly-named module, Somecommand.hs. + +Each command's help is kept in Somecommand.md. +This file is included by Somecommand.hs to help build the command's --help output, +and by hledger/hledger_commands.m4.md to help build the hledger manual. +It has some special features: + +- The first line should specify the command name and any aliases, + as space or comma-separated words. + +- A line containing just _FLAGS_ will be replaced in --help output by + the command's flags list. If there's no such line, the flags will be + displayed at the end. In the manual, no flags list is shown. + +- Markdown can be used to influence the appearance of the manuals, + especially the html version. But the markup will also appear + uninterpreted in the --help output, so use sparingly. + +- GHC (and ghcid etc.) won't notice changes in this file; + you have to also touch the .hs file. diff --git a/hledger/hledger_commands.m4.md b/hledger/hledger_commands.m4.md index 211e0ab58..32dbffab8 100644 --- a/hledger/hledger_commands.m4.md +++ b/hledger/hledger_commands.m4.md @@ -362,11 +362,8 @@ Report account names having the same leaf but different prefixes. An example: http://stefanorodighiero.net/software/hledger-dupes.html ## close -Print closing/opening transactions that bring some or all account balances to zero and back. -Can be useful for bringing asset/liability balances across file boundaries, -or for closing out income/expenses for a period. -This was formerly called "equity", as in Ledger, and that alias is also accepted. -See close --help for more. + +_include_(Hledger/Cli/Commands/Close.md) ## files List all files included in the journal. With a REGEX argument,