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

;journal: doc: drop "transaction modifiers", just say "auto postings"

Browse Source
This commit is contained in:
Simon Michael 2020-03-18 15:11:31 -07:00
parent 31edd54c1a
commit abc53024fc
2 changed files with 24 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
doc/common.m4
View File

@ -148,7 +148,7 @@ m4_define({{_reportingoptions_}}, {{
(using the most recent applicable [market price](journal.html#market-prices), if any)
`--auto`
: apply [automated posting rules](journal.html#auto-postings-transaction-modifiers) to modify transactions.
: apply [automated posting rules](journal.html#auto-postings) to modify transactions.
`--forecast`
: generate future transactions from [periodic transaction](journal.html#periodic-transactions) rules, for the next 6 months or till report end date.

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

@ -796,7 +796,7 @@ so here is a table summarising the directives and their effects, with links to m
[`include`]: #including-other-files
[`P`]: #market-prices
[`Y`]: #default-year
[`=`]: #auto-postings-transaction-modifiers
[`=`]: #auto-postings
And some definitions:
@ -1424,33 +1424,35 @@ and
<a name="automated-postings"></a>
<a name="auto-postings"></a>
## Auto postings / transaction modifiers
## Auto postings
Transaction modifier rules, AKA auto posting rules, describe changes to be applied automatically to certain matched transactions.
Currently just one kind of change is possible - adding extra postings, which we call "automated postings" or just "auto postings".
These rules become active when you use the `--auto` flag.
A transaction modifier rule looks much like a normal transaction
except the first line is an equals sign followed by a
[query](hledger.html#queries) that matches certain postings
(mnemonic: `=` suggests matching).
And each "posting" is actually a posting-generating rule:
"Automated postings" or "auto postings" are extra postings which get
added automatically to transactions which match certain queries,
defined by "auto posting rules", when you use the `--auto` flag.
An auto posting rule looks a bit like a transaction:
```journal
= QUERY
ACCOUNT AMOUNT
ACCOUNT [AMOUNT]
...
ACCOUNT [AMOUNT]
```
These posting-generating rules look like normal postings, except the amount can be:
except the first line is an equals sign (mnemonic: `=` suggests matching),
followed by a [query](hledger.html#queries) (which matches existing postings),
and each "posting" line describes a posting to be generated,
and the posting amounts can be:
- a normal amount with a commodity symbol, eg `$2`. This will be used as-is.
- a number, eg `2`. The commodity symbol (if any) from the matched posting will be added to this.
- a numeric multiplier, eg `*2` (a star followed by a number N). The matched posting's amount (and total price, if any) will be multiplied by N.
- a multiplier with a commodity symbol, eg `*$2` (a star, number N, and symbol S). The matched posting's amount will be multiplied by N, and its commodity symbol will be replaced with S.
- a number, eg `2`. The commodity symbol (if any) from the matched
posting will be added to this.
- a numeric multiplier, eg `*2` (a star followed by a number N). The
matched posting's amount (and total price, if any) will be
multiplied by N.
- a multiplier with a commodity symbol, eg `*$2` (a star, number N,
and symbol S). The matched posting's amount will be multiplied by N,
and its commodity symbol will be replaced with S.
A query term containing spaces must be enclosed in single or double
Any query term containing spaces must be enclosed in single or double
quotes, as on the command line. Eg, note the quotes around the second query term below:
```journal
= expenses:groceries 'expenses:dining out'
@ -1505,7 +1507,7 @@ will also be used in the generated posting.
### Auto postings and transaction balancing / inferred amounts / balance assertions
Currently, transaction modifiers are applied / auto postings are added:
Currently, auto postings are added:
- after [missing amounts are inferred, and transactions are checked for balancedness](#postings),
- but before [balance assertions](#balance-assertions) are checked.
@ -1517,14 +1519,14 @@ background.
### Auto posting tags
Postings added by transaction modifiers will have some extra [tags](#tags-1):
Automated postings will have some extra [tags](#tags-1):
- `generated-posting:= QUERY` - shows this was generated by an auto posting rule, and the query
- `_generated-posting:= QUERY` - a hidden tag, which does not appear in hledger's output.
This can be used to match postings generated "just now",
rather than generated in the past and saved to the journal.
Also, any transaction that has been changed by transaction modifier rules will have these tags added:
Also, any transaction that has been changed by auto posting rules will have these tags added:
- `modified:` - this transaction was modified
- `_modified:` - a hidden tag not appearing in the comment; this transaction was modified "just now".