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

lib,cli: auto/forecast/budget option/docs cleanup, consistency

Browse Source
This commit is contained in:
Simon Michael 2017-12-31 10:01:18 -08:00
parent 667a1d7e59
commit e927e587e6
5 changed files with 35 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
doc/lib.m4
View File

@ -156,14 +156,12 @@ m4_define({{_reportingoptions_}}, {{
: convert amounts to their market value on the report end date
(using the most recent applicable [market price](journal.html#market-prices), if any)
`--forecast`
: generate forecast transactions from [periodic transaction](journal.html#periodic-transactions) rules.
Each periodic transaction rule will generate [forecast transactions](budgeting-and-forecasting.html#forecasting),
beginning the day after the last recorded journal transaction,
and ending 6 months from today, or at the specified report end date.
`--auto`
: apply [automated posting rules](journal.html#automated-posting-rules) to modify transactions where applicable (can combine with --forecast).
: apply [automated posting rules](journal.html#automated-posting-rules) to modify transactions.
`--forecast`
: apply [periodic transaction](journal.html#periodic-transactions) rules to generate future transactions, to 6 months from now or report end date.
When a reporting option appears more than once in the command line, the last one takes precedence.

12
hledger-lib/hledger_journal.m4.md
View File

@ -865,12 +865,18 @@ A periodic transaction starts with a tilde ‘~’ in place of a date followed b
income:acme inc
```
Periodic transactions are used for budgeting and forecasting only, they have no effect without the `--forecast` or `--budget` option specified.
For examples and details, see [Budgeting and Forecasting](budgeting-and-forecasting.html).
Periodic transactions are used for forecasting and budgeting only, they have no effect unless the `--forecast` or `--budget` flag is used.
With `--forecast`, each periodic transaction rule generates recurring forecast transactions
at the specified interval, beginning the day after the last recorded journal transaction
and ending 6 months from today, or at the specified report end date.
With `balance --budget`, each periodic transaction declares recurring budget goals for one or more accounts.
For more details, see:
[balance > Budgeting](manual.html#budgeting),
[Budgeting and Forecasting](budgeting-and-forecasting.html).
# Automated posting rules
Autopated posting rule starts with an equal sign '=' in place of a date, followed by a [query](manual.html#queries):
Automated posting rule starts with an equal sign '=' in place of a date, followed by a [query](manual.html#queries):
```journal
= expenses:gifts
budget:gifts *-1

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

@ -155,8 +155,8 @@ reportflags = [
,flagNone ["empty","E"] (setboolopt "empty") "show items with zero amount, normally hidden"
,flagNone ["cost","B"] (setboolopt "cost") "convert amounts to their cost at transaction time (using the transaction price, if any)"
,flagNone ["value","V"] (setboolopt "value") "convert amounts to their market value on the report end date (using the most recent applicable market price, if any)"
,flagNone ["forecast"] (setboolopt "forecast") "apply periodic transaction rules to generate future transactions, 6 months into the future or to report end date"
,flagNone ["auto"] (setboolopt "auto") "apply automated posting rules to modify transactions where applicable (can combine with --forecast)"
,flagNone ["auto"] (setboolopt "auto") "apply automated posting rules to modify transactions"
,flagNone ["forecast"] (setboolopt "forecast") "apply periodic transaction rules to generate future transactions, to 6 months from now or report end date"
]
-- | Common output-related flags: --output-file, --output-format...

8
hledger/Hledger/Cli/Commands/Balance.hs
View File

@ -283,10 +283,10 @@ balancemode = (defCommandMode $ ["balance"] ++ aliases) { -- also accept but don
,flagReq ["drop"] (\s opts -> Right $ setopt "drop" s opts) "N" "omit N leading account name parts (in flat mode)"
,flagNone ["no-elide"] (\opts -> setboolopt "no-elide" opts) "don't squash boring parent accounts (in tree mode)"
,flagReq ["format"] (\s opts -> Right $ setopt "format" s opts) "FORMATSTR" "use this custom line format (in simple reports)"
,flagNone ["pretty-tables"] (\opts -> setboolopt "pretty-tables" opts) "use unicode when displaying tables"
,flagNone ["sort-amount","S"] (\opts -> setboolopt "sort-amount" opts) "sort by amount instead of account name"
,flagNone ["budget"] (setboolopt "budget") "compute budget from periodic transactions and compare real balances to it"
,flagNone ["show-unbudgeted"] (setboolopt "show-unbudgeted") "show full names of accounts not mentioned in budget"
,flagNone ["pretty-tables"] (\opts -> setboolopt "pretty-tables" opts) "use unicode to display prettier tables"
,flagNone ["sort-amount","S"] (\opts -> setboolopt "sort-amount" opts) "sort by amount instead of account name (in flat mode). With multiple columns, sorts by the row total, or by row average if that is displayed."
,flagNone ["budget"] (setboolopt "budget") "show performance compared to budget goals defined by periodic transactions"
,flagNone ["show-unbudgeted"] (setboolopt "show-unbudgeted") "with --budget, show unbudgeted accounts also"
]
++ outputflags
,groupHidden = []

23
hledger/hledger_balance.m4.md
View File

@ -42,16 +42,16 @@ txt, csv.
: write output to FILE. A file extension matching one of the above formats selects that format.
`--pretty-tables`
: Use unicode to display prettier tables.
: use unicode to display prettier tables.
`--sort-amount`
: Sort by amount (total row amount, or by average if that is displayed), instead of account name (in flat mode)
: sort by amount instead of account name (in flat mode). With multiple columns, sorts by the row total, or by row average if that is displayed.
`--budget`
: Treat [periodic transaction](journal.html#periodic-transactions) as definition of a budget. Compare real balances to budget balances and show percentage of budget consumed.
: show performance compared to budget goals defined by [periodic transactions](journal.html#periodic-transactions)
`--show-unbudgeted`
: When --budget is used, display accounts that do not have budget defined
: with --budget, show unbudgeted accounts also
The balance command displays accounts and balances.
It is hledger's most featureful and versatile command.
@ -244,7 +244,12 @@ Balance changes in 2008:
### Budgets
The `--budget` flag will treat all [periodic transaction](journal.html#periodic-transactions) in your journal as definition of the budget and allow you to compare real balances versus budgeted amounts.
With `--budget` and a [report interval](manual.html#report-intervals),
all [periodic transactions](journal.html#periodic-transactions) in your journal
with that interval,
active during the requested report period,
are interpreted as recurring budget goals for the specified accounts (and subaccounts),
and the report will show the difference between actual and budgeted balances.
For example, you can take average monthly expenses in the common expense categories to construct a minimal monthly budget:
```journal
@ -273,9 +278,9 @@ For example, you can take average monthly expenses in the common expense categor
assets:bank:checking
```
You can now compare real balances with budget:
You can now see a monthly budget performance report:
```shell
$ hledge balance -M --budget
$ hledger balance -M --budget
Balance changes in 2017/11/01-2017/12/31:
|| 2017/11 2017/12
@ -307,7 +312,9 @@ Ending balances (cumulative) in 2017/11/01-2017/12/31:
|| 0 0
```
Adding `--show-unbudgeted` will allow you to see all the accounts for which budgets:
Accounts with no budget goals (not mentioned in the periodic transactions)
will be aggregated under `<unbudgeted>`, unless you add the
`--show-unbudgeted` flag to display them normally:
```shell
$ hledger balance --budget --show-unbudgeted
Balance changes in 2017/11/01-2017/12/31: