doc: journal: mention "auto postings"; explain the #893 situation
[ci skip]
This commit is contained in:
Simon Michael
parent
d1f122f15e
commit
022dc09f11
@ -1659,13 +1659,14 @@ Goals and actual performance can then be compared in budget reports.
|
||||
For more details, see: balance: Budget report and Cookbook: Budgeting
|
||||
and Forecasting.
|
||||
.PP
|
||||
.SS Transaction Modifiers
|
||||
.SS Transaction modifiers
|
||||
.PP
|
||||
Transaction modifier rules describe changes that should be applied
|
||||
automatically to certain transactions.
|
||||
Currently, this means adding extra postings (also known as "automated
|
||||
postings").
|
||||
Transaction modifiers are enabled by the \f[C]\-\-auto\f[] flag.
|
||||
They can be enabled by using the \f[C]\-\-auto\f[] flag.
|
||||
Currently, just one kind of change is possible: adding extra postings.
|
||||
These rule\-generated postings are known as "automated postings" or
|
||||
"auto postings".
|
||||
.PP
|
||||
A transaction modifier rule looks quite like a normal transaction,
|
||||
except the first line is an equals sign followed by a query that matches
|
||||
@ -1681,8 +1682,7 @@ And each "posting" is actually a posting\-generating rule:
|
||||
\f[]
|
||||
.fi
|
||||
.PP
|
||||
The posting rules look just like normal postings, except the amount can
|
||||
be:
|
||||
These posting rules look like normal postings, except the amount can be:
|
||||
.IP \[bu] 2
|
||||
a normal amount with a commodity symbol, eg \f[C]$2\f[].
|
||||
This will be used as\-is.
|
||||
@ -1738,10 +1738,20 @@ $\ hledger\ print\ \-\-auto
|
||||
\ \ \ \ assets:checking\ \ \ \ \ \ \ \ \ \ \ \ $20
|
||||
\f[]
|
||||
.fi
|
||||
.SS Transaction modifiers and transaction balancing / inferred amounts /
|
||||
balance assertions
|
||||
.PP
|
||||
Postings added by transaction modifiers participate in transaction
|
||||
balancing, missing amount inference and balance assertions, like regular
|
||||
postings.
|
||||
Currently, transaction modifiers are applied / auto postings are added:
|
||||
.IP \[bu] 2
|
||||
after missing amounts are inferred, and transactions are checked for
|
||||
balancedness,
|
||||
.IP \[bu] 2
|
||||
but before balance assertions are checked.
|
||||
.PP
|
||||
This means that journal entries must be balanced both before and after
|
||||
auto postings are added.
|
||||
This has changed in hledger 1.12+.
|
||||
For some background discussion, see #893, #928, #938.
|
||||
.SH EDITOR SUPPORT
|
||||
.PP
|
||||
Add\-on modes exist for various text editors, to make working with
|
||||
|
||||
@ -82,7 +82,7 @@ File: hledger_journal.info, Node: FILE FORMAT, Next: EDITOR SUPPORT, Prev: To
|
||||
* Tags::
|
||||
* Directives::
|
||||
* Periodic transactions::
|
||||
* Transaction Modifiers::
|
||||
* Transaction modifiers::
|
||||
|
||||
|
||||
File: hledger_journal.info, Node: Transactions, Next: Postings, Up: FILE FORMAT
|
||||
@ -1378,7 +1378,7 @@ If account aliases are present, they are applied after the default
|
||||
parent account.
|
||||
|
||||
|
||||
File: hledger_journal.info, Node: Periodic transactions, Next: Transaction Modifiers, Prev: Directives, Up: FILE FORMAT
|
||||
File: hledger_journal.info, Node: Periodic transactions, Next: Transaction modifiers, Prev: Directives, Up: FILE FORMAT
|
||||
|
||||
1.15 Periodic transactions
|
||||
==========================
|
||||
@ -1488,15 +1488,16 @@ compared in budget reports.
|
||||
and Forecasting.
|
||||
|
||||
|
||||
File: hledger_journal.info, Node: Transaction Modifiers, Prev: Periodic transactions, Up: FILE FORMAT
|
||||
File: hledger_journal.info, Node: Transaction modifiers, Prev: Periodic transactions, Up: FILE FORMAT
|
||||
|
||||
1.16 Transaction Modifiers
|
||||
1.16 Transaction modifiers
|
||||
==========================
|
||||
|
||||
Transaction modifier rules describe changes that should be applied
|
||||
automatically to certain transactions. Currently, this means adding
|
||||
extra postings (also known as "automated postings"). Transaction
|
||||
modifiers are enabled by the '--auto' flag.
|
||||
automatically to certain transactions. They can be enabled by using the
|
||||
'--auto' flag. Currently, just one kind of change is possible: adding
|
||||
extra postings. These rule-generated postings are known as "automated
|
||||
postings" or "auto postings".
|
||||
|
||||
A transaction modifier rule looks quite like a normal transaction,
|
||||
except the first line is an equals sign followed by a query that matches
|
||||
@ -1508,8 +1509,8 @@ is actually a posting-generating rule:
|
||||
ACCT [AMT]
|
||||
...
|
||||
|
||||
The posting rules look just like normal postings, except the amount
|
||||
can be:
|
||||
These posting rules look like normal postings, except the amount can
|
||||
be:
|
||||
|
||||
* a normal amount with a commodity symbol, eg '$2'. This will be
|
||||
used as-is.
|
||||
@ -1553,9 +1554,26 @@ $ hledger print --auto
|
||||
assets:checking:gifts -$20
|
||||
assets:checking $20
|
||||
|
||||
Postings added by transaction modifiers participate in transaction
|
||||
balancing, missing amount inference and balance assertions, like regular
|
||||
postings.
|
||||
* Menu:
|
||||
|
||||
* Transaction modifiers and transaction balancing / inferred amounts / balance assertions::
|
||||
|
||||
|
||||
File: hledger_journal.info, Node: Transaction modifiers and transaction balancing / inferred amounts / balance assertions, Up: Transaction modifiers
|
||||
|
||||
1.16.1 Transaction modifiers and transaction balancing / inferred
|
||||
-----------------------------------------------------------------
|
||||
|
||||
amounts / balance assertions Currently, transaction modifiers are
|
||||
applied / auto postings are added:
|
||||
|
||||
* after missing amounts are inferred, and transactions are checked
|
||||
for balancedness,
|
||||
* but before balance assertions are checked.
|
||||
|
||||
This means that journal entries must be balanced both before and
|
||||
after auto postings are added. This has changed in hledger 1.12+. For
|
||||
some background discussion, see #893, #928, #938.
|
||||
|
||||
|
||||
File: hledger_journal.info, Node: EDITOR SUPPORT, Prev: FILE FORMAT, Up: Top
|
||||
@ -1685,9 +1703,11 @@ Node: Forecasting with periodic transactions52482
|
||||
Ref: #forecasting-with-periodic-transactions52772
|
||||
Node: Budgeting with periodic transactions54459
|
||||
Ref: #budgeting-with-periodic-transactions54698
|
||||
Node: Transaction Modifiers55157
|
||||
Node: Transaction modifiers55157
|
||||
Ref: #transaction-modifiers55320
|
||||
Node: EDITOR SUPPORT57301
|
||||
Ref: #editor-support57419
|
||||
Node: Transaction modifiers and transaction balancing / inferred amounts / balance assertions57312
|
||||
Ref: #transaction-modifiers-and-transaction-balancing-inferred-amounts-balance-assertions57627
|
||||
Node: EDITOR SUPPORT58034
|
||||
Ref: #editor-support58152
|
||||
|
||||
End Tag Table
|
||||
|
||||
@ -1229,12 +1229,14 @@ and
|
||||
|
||||
|
||||
<a name="automated-postings"></a>
|
||||
<a name="auto-postings"></a>
|
||||
|
||||
## Transaction Modifiers
|
||||
## Transaction modifiers
|
||||
|
||||
Transaction modifier rules describe changes that should be applied automatically to certain transactions.
|
||||
Currently, this means adding extra postings (also known as "automated postings").
|
||||
Transaction modifiers are enabled by the `--auto` flag.
|
||||
They can be enabled by using the `--auto` flag.
|
||||
Currently, just one kind of change is possible: adding extra postings.
|
||||
These rule-generated postings are known as "automated postings" or "auto postings".
|
||||
|
||||
A transaction modifier rule looks quite like a normal transaction,
|
||||
except the first line is an equals sign followed by a [query](manual.html#queries) that matches certain postings
|
||||
@ -1248,7 +1250,7 @@ And each "posting" is actually a posting-generating rule:
|
||||
...
|
||||
```
|
||||
|
||||
The posting rules look just like normal postings, except the amount can be:
|
||||
These posting rules look like normal postings, except the amount 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.
|
||||
@ -1288,18 +1290,24 @@ $ hledger print --auto
|
||||
assets:checking $20
|
||||
```
|
||||
|
||||
### Auto postings and transaction balancing / inferred amounts / balance assertions
|
||||
|
||||
Postings added by transaction modifiers participate in
|
||||
[transaction balancing, missing amount inference](#postings)
|
||||
and [balance assertions](#balance-assertions),
|
||||
like regular postings.
|
||||
Currently, transaction modifiers are applied / auto postings are added:
|
||||
|
||||
- after [missing amounts are inferred, and transactions are checked for balancedness](#postings),
|
||||
- but before [balance assertions](#balance-assertions) are checked.
|
||||
|
||||
Note this means that journal entries must be balanced both before and
|
||||
after auto postings are added. This changed in hledger 1.12+; see
|
||||
[#893](https://github.com/simonmichael/hledger/issues/893) for
|
||||
background.
|
||||
|
||||
# EDITOR SUPPORT
|
||||
|
||||
Add-on modes exist for various text editors, to make working with journal
|
||||
files easier. They add colour, navigation aids and helpful commands.
|
||||
For hledger users who edit the journal file directly (the majority),
|
||||
using one of these modes is quite recommended.
|
||||
Add-on modes exist for various text editors, to make working with
|
||||
journal files easier. They add colour, navigation aids and helpful
|
||||
commands. For hledger users who edit the journal file directly (the
|
||||
majority), using one of these modes is quite recommended.
|
||||
|
||||
These were written with Ledger in mind, but also work with hledger files:
|
||||
|
||||
|
||||
@ -1195,15 +1195,16 @@ FILE FORMAT
|
||||
and Forecasting.
|
||||
|
||||
|
||||
Transaction Modifiers
|
||||
Transaction modifiers
|
||||
Transaction modifier rules describe changes that should be applied
|
||||
automatically to certain transactions. Currently, this means adding
|
||||
extra postings (also known as "automated postings"). Transaction modi-
|
||||
fiers are enabled by the --auto flag.
|
||||
automatically to certain transactions. They can be enabled by using
|
||||
the --auto flag. Currently, just one kind of change is possible:
|
||||
adding extra postings. These rule-generated postings are known as
|
||||
"automated postings" or "auto postings".
|
||||
|
||||
A transaction modifier rule looks quite like a normal transaction,
|
||||
except the first line is an equals sign followed by a query that
|
||||
matches certain postings (mnemonic: = suggests matching). And each
|
||||
A transaction modifier rule looks quite like a normal transaction,
|
||||
except the first line is an equals sign followed by a query that
|
||||
matches certain postings (mnemonic: = suggests matching). And each
|
||||
"posting" is actually a posting-generating rule:
|
||||
|
||||
= QUERY
|
||||
@ -1211,20 +1212,20 @@ FILE FORMAT
|
||||
ACCT [AMT]
|
||||
...
|
||||
|
||||
The posting rules look just like normal postings, except the amount can
|
||||
These posting rules look like normal postings, except the amount can
|
||||
be:
|
||||
|
||||
o a normal amount with a commodity symbol, eg $2. This will be used
|
||||
o a normal amount with a commodity symbol, eg $2. This will be used
|
||||
as-is.
|
||||
|
||||
o a number, eg 2. The commodity symbol (if any) from the matched post-
|
||||
ing will be added to this.
|
||||
|
||||
o a numeric multiplier, eg *2 (a star followed by a number N). The
|
||||
o 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.
|
||||
|
||||
o a multiplier with a commodity symbol, eg *$2 (a star, number N, and
|
||||
o 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.
|
||||
|
||||
@ -1259,17 +1260,27 @@ FILE FORMAT
|
||||
assets:checking:gifts -$20
|
||||
assets:checking $20
|
||||
|
||||
Postings added by transaction modifiers participate in transaction bal-
|
||||
ancing, missing amount inference and balance assertions, like regular
|
||||
postings.
|
||||
Transaction modifiers and transaction balancing / inferred amounts /
|
||||
balance assertions
|
||||
|
||||
Currently, transaction modifiers are applied / auto postings are added:
|
||||
|
||||
o after missing amounts are inferred, and transactions are checked for
|
||||
balancedness,
|
||||
|
||||
o but before balance assertions are checked.
|
||||
|
||||
This means that journal entries must be balanced both before and after
|
||||
auto postings are added. This has changed in hledger 1.12+. For some
|
||||
background discussion, see #893, #928, #938.
|
||||
|
||||
EDITOR SUPPORT
|
||||
Add-on modes exist for various text editors, to make working with jour-
|
||||
nal files easier. They add colour, navigation aids and helpful com-
|
||||
mands. For hledger users who edit the journal file directly (the
|
||||
nal files easier. They add colour, navigation aids and helpful com-
|
||||
mands. For hledger users who edit the journal file directly (the
|
||||
majority), using one of these modes is quite recommended.
|
||||
|
||||
These were written with Ledger in mind, but also work with hledger
|
||||
These were written with Ledger in mind, but also work with hledger
|
||||
files:
|
||||
|
||||
|
||||
@ -1280,6 +1291,7 @@ EDITOR SUPPORT
|
||||
Sublime Text https://github.com/ledger/ledger/wiki/Edit-
|
||||
ing-Ledger-files-with-Sublime-Text-or-RubyMine
|
||||
Textmate https://github.com/ledger/ledger/wiki/Using-TextMate-2
|
||||
|
||||
Text Wran- https://github.com/ledger/ledger/wiki/Edit-
|
||||
gler ing-Ledger-files-with-TextWrangler
|
||||
Visual Stu- https://marketplace.visualstudio.com/items?item-
|
||||
@ -1288,7 +1300,7 @@ EDITOR SUPPORT
|
||||
|
||||
|
||||
REPORTING BUGS
|
||||
Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
|
||||
Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
|
||||
or hledger mail list)
|
||||
|
||||
|
||||
@ -1302,7 +1314,7 @@ COPYRIGHT
|
||||
|
||||
|
||||
SEE ALSO
|
||||
hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
|
||||
hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
|
||||
hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time-
|
||||
dot(5), ledger(1)
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user