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

doc: begin integrating commands' CLI help and manual section

Browse Source 
Just the close command to start with.
This commit is contained in:
Simon Michael 2019-01-22 13:33:24 -08:00
parent fbaaaac680
commit cc7c3928fb
6 changed files with 131 additions and 73 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
doc/lib.m4
View File

@ -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

40
hledger/Hledger/Cli/CliOptions.hs
View File

@ -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,10 +263,10 @@ 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
modeHelp = shorthelp
,modeHelpSuffix = longhelplines
,modeGroupFlags = Group {
groupUnnamed = ungroupedflags
,groupNamed = groupedflags

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

@ -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"
]

79
hledger/Hledger/Cli/Commands/Close.md Normal file
View File

@ -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

22
hledger/Hledger/Cli/Commands/README Normal file
View File

@ -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.

7
hledger/hledger_commands.m4.md
View File

@ -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,