Skip to content
Permalink
Browse files

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

  • Loading branch information
simonmichael committed Mar 18, 2020
1 parent 31edd54 commit abc53024fc62515060ddd81c002d6fbe67351666
Showing with 25 additions and 23 deletions.
  1. +1 −1 doc/common.m4
  2. +24 −22 hledger-lib/hledger_journal.m4.md
@@ -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.
@@ -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 query term containing spaces must be enclosed in single or double
- 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.

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

0 comments on commit abc5302

Please sign in to comment.
You can’t perform that action at this time.