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) (using the most recent applicable [market price](journal.html#market-prices), if any)
`--auto` `--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` `--forecast`
: generate future transactions from [periodic transaction](journal.html#periodic-transactions) rules, for the next 6 months or till report end date. : 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 [`include`]: #including-other-files
[`P`]: #market-prices [`P`]: #market-prices
[`Y`]: #default-year [`Y`]: #default-year
[`=`]: #auto-postings-transaction-modifiers [`=`]: #auto-postings
And some definitions: And some definitions:
@ -1424,33 +1424,35 @@ and
<a name="automated-postings"></a> <a name="automated-postings"></a>
<a name="auto-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. "Automated postings" or "auto postings" are extra postings which get
Currently just one kind of change is possible - adding extra postings, which we call "automated postings" or just "auto postings". added automatically to transactions which match certain queries,
These rules become active when you use the `--auto` flag. defined by "auto posting rules", 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:
An auto posting rule looks a bit like a transaction:
```journal ```journal
= QUERY = QUERY
ACCOUNT AMOUNT ACCOUNT AMOUNT
ACCOUNT [AMOUNT]
... ...
ACCOUNT [AMOUNT]
``` ```
except the first line is an equals sign (mnemonic: `=` suggests matching),
These posting-generating rules look like normal postings, except the amount can be: 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 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 number, eg `2`. The commodity symbol (if any) from the matched
- 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. posting will be added to this.
- 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 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: quotes, as on the command line. Eg, note the quotes around the second query term below:
```journal ```journal
= expenses:groceries 'expenses:dining out' = 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 ### 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), - after [missing amounts are inferred, and transactions are checked for balancedness](#postings),
- but before [balance assertions](#balance-assertions) are checked. - but before [balance assertions](#balance-assertions) are checked.
@ -1517,14 +1519,14 @@ background.
### Auto posting tags ### 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` - 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. - `_generated-posting:= QUERY` - a hidden tag, which does not appear in hledger's output.
This can be used to match postings generated "just now", This can be used to match postings generated "just now",
rather than generated in the past and saved to the journal. 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:` - this transaction was modified
- `_modified:` - a hidden tag not appearing in the comment; this transaction was modified "just now". - `_modified:` - a hidden tag not appearing in the comment; this transaction was modified "just now".