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

doc: journal: mention "auto postings"; explain the #893 situation

Browse Source 
[ci skip]
This commit is contained in:
Simon Michael 2019-02-01 16:06:09 -08:00
parent d1f122f15e
commit 022dc09f11
4 changed files with 105 additions and 55 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
hledger-lib/hledger_journal.5
View File

@ -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 For more details, see: balance: Budget report and Cookbook: Budgeting
and Forecasting. and Forecasting.
.PP .PP
.SS Transaction Modifiers .SS Transaction modifiers
.PP .PP
Transaction modifier rules describe changes that should be applied Transaction modifier rules describe changes that should be applied
automatically to certain transactions. automatically to certain transactions.
Currently, this means adding extra postings (also known as "automated They can be enabled by using the \f[C]\-\-auto\f[] flag.
postings"). Currently, just one kind of change is possible: adding extra postings.
Transaction modifiers are enabled by the \f[C]\-\-auto\f[] flag. These rule\-generated postings are known as "automated postings" or
"auto postings".
.PP .PP
A transaction modifier rule looks quite like a normal transaction, A transaction modifier rule looks quite like a normal transaction,
except the first line is an equals sign followed by a query that matches 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[] \f[]
.fi .fi
.PP .PP
The posting rules look just like normal postings, except the amount can These posting rules look like normal postings, except the amount can be:
be:
.IP \[bu] 2 .IP \[bu] 2
a normal amount with a commodity symbol, eg \f[C]$2\f[]. a normal amount with a commodity symbol, eg \f[C]$2\f[].
This will be used as\-is. This will be used as\-is.
@ -1738,10 +1738,20 @@ $\ hledger\ print\ \-\-auto
\ \ \ \ assets:checking\ \ \ \ \ \ \ \ \ \ \ \ $20 \ \ \ \ assets:checking\ \ \ \ \ \ \ \ \ \ \ \ $20
\f[] \f[]
.fi .fi
.SS Transaction modifiers and transaction balancing / inferred amounts /
balance assertions
.PP .PP
Postings added by transaction modifiers participate in transaction Currently, transaction modifiers are applied / auto postings are added:
balancing, missing amount inference and balance assertions, like regular .IP \[bu] 2
postings. 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 .SH EDITOR SUPPORT
.PP .PP
Add\-on modes exist for various text editors, to make working with Add\-on modes exist for various text editors, to make working with

50
hledger-lib/hledger_journal.info
View File

@ -82,7 +82,7 @@ File: hledger_journal.info, Node: FILE FORMAT, Next: EDITOR SUPPORT, Prev: To
* Tags:: * Tags::
* Directives:: * Directives::
* Periodic transactions:: * Periodic transactions::
* Transaction Modifiers:: * Transaction modifiers::
 
File: hledger_journal.info, Node: Transactions, Next: Postings, Up: FILE FORMAT 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. 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 1.15 Periodic transactions
========================== ==========================
@ -1488,15 +1488,16 @@ compared in budget reports.
and Forecasting. 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 Transaction modifier rules describe changes that should be applied
automatically to certain transactions. Currently, this means adding automatically to certain transactions. They can be enabled by using the
extra postings (also known as "automated postings"). Transaction '--auto' flag. Currently, just one kind of change is possible: adding
modifiers are enabled by the '--auto' flag. extra postings. These rule-generated postings are known as "automated
postings" or "auto postings".
A transaction modifier rule looks quite like a normal transaction, A transaction modifier rule looks quite like a normal transaction,
except the first line is an equals sign followed by a query that matches 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] ACCT [AMT]
... ...
The posting rules look just like normal postings, except the amount These posting rules look like normal postings, except the amount can
can be: be:
* a normal amount with a commodity symbol, eg '$2'. This will be * a normal amount with a commodity symbol, eg '$2'. This will be
used as-is. used as-is.
@ -1553,9 +1554,26 @@ $ hledger print --auto
assets:checking:gifts -$20 assets:checking:gifts -$20
assets:checking $20 assets:checking $20
Postings added by transaction modifiers participate in transaction * Menu:
balancing, missing amount inference and balance assertions, like regular
postings. * 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 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 Ref: #forecasting-with-periodic-transactions52772
Node: Budgeting with periodic transactions54459 Node: Budgeting with periodic transactions54459
Ref: #budgeting-with-periodic-transactions54698 Ref: #budgeting-with-periodic-transactions54698
Node: Transaction Modifiers55157 Node: Transaction modifiers55157
Ref: #transaction-modifiers55320 Ref: #transaction-modifiers55320
Node: EDITOR SUPPORT57301 Node: Transaction modifiers and transaction balancing / inferred amounts / balance assertions57312
Ref: #editor-support57419 Ref: #transaction-modifiers-and-transaction-balancing-inferred-amounts-balance-assertions57627
Node: EDITOR SUPPORT58034
Ref: #editor-support58152
 
End Tag Table End Tag Table

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

@ -1229,12 +1229,14 @@ and
<a name="automated-postings"></a> <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. Transaction modifier rules describe changes that should be applied automatically to certain transactions.
Currently, this means adding extra postings (also known as "automated postings"). They can be enabled by using the `--auto` flag.
Transaction modifiers are enabled by 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, 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 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 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 posting will be added to this.
@ -1288,18 +1290,24 @@ $ hledger print --auto
assets:checking $20 assets:checking $20
``` ```
### Auto postings and transaction balancing / inferred amounts / balance assertions
Postings added by transaction modifiers participate in Currently, transaction modifiers are applied / auto postings are added:
[transaction balancing, missing amount inference](#postings)
and [balance assertions](#balance-assertions), - after [missing amounts are inferred, and transactions are checked for balancedness](#postings),
like regular 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 # EDITOR SUPPORT
Add-on modes exist for various text editors, to make working with journal Add-on modes exist for various text editors, to make working with
files easier. They add colour, navigation aids and helpful commands. journal files easier. They add colour, navigation aids and helpful
For hledger users who edit the journal file directly (the majority), commands. For hledger users who edit the journal file directly (the
using one of these modes is quite recommended. majority), using one of these modes is quite recommended.
These were written with Ledger in mind, but also work with hledger files: These were written with Ledger in mind, but also work with hledger files:

50
hledger-lib/hledger_journal.txt
View File

@ -1195,15 +1195,16 @@ FILE FORMAT
and Forecasting. and Forecasting.
Transaction Modifiers Transaction modifiers
Transaction modifier rules describe changes that should be applied Transaction modifier rules describe changes that should be applied
automatically to certain transactions. Currently, this means adding automatically to certain transactions. They can be enabled by using
extra postings (also known as "automated postings"). Transaction modi- the --auto flag. Currently, just one kind of change is possible:
fiers are enabled by the --auto flag. 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, A transaction modifier rule looks quite like a normal transaction,
except the first line is an equals sign followed by a query that except the first line is an equals sign followed by a query that
matches certain postings (mnemonic: = suggests matching). And each matches certain postings (mnemonic: = suggests matching). And each
"posting" is actually a posting-generating rule: "posting" is actually a posting-generating rule:
= QUERY = QUERY
@ -1211,20 +1212,20 @@ FILE FORMAT
ACCT [AMT] 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: 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. as-is.
o a number, eg 2. The commodity symbol (if any) from the matched post- o a number, eg 2. The commodity symbol (if any) from the matched post-
ing will be added to this. 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 matched posting's amount (and total price, if any) will be multiplied
by N. 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 symbol S). The matched posting's amount will be multiplied by N, and
its commodity symbol will be replaced with S. its commodity symbol will be replaced with S.
@ -1259,17 +1260,27 @@ FILE FORMAT
assets:checking:gifts -$20 assets:checking:gifts -$20
assets:checking $20 assets:checking $20
Postings added by transaction modifiers participate in transaction bal- Transaction modifiers and transaction balancing / inferred amounts /
ancing, missing amount inference and balance assertions, like regular balance assertions
postings.
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 EDITOR SUPPORT
Add-on modes exist for various text editors, to make working with jour- Add-on modes exist for various text editors, to make working with jour-
nal files easier. They add colour, navigation aids and helpful com- nal files easier. They add colour, navigation aids and helpful com-
mands. For hledger users who edit the journal file directly (the mands. For hledger users who edit the journal file directly (the
majority), using one of these modes is quite recommended. 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: files:
@ -1280,6 +1291,7 @@ EDITOR SUPPORT
Sublime Text https://github.com/ledger/ledger/wiki/Edit- Sublime Text https://github.com/ledger/ledger/wiki/Edit-
ing-Ledger-files-with-Sublime-Text-or-RubyMine ing-Ledger-files-with-Sublime-Text-or-RubyMine
Textmate https://github.com/ledger/ledger/wiki/Using-TextMate-2 Textmate https://github.com/ledger/ledger/wiki/Using-TextMate-2
Text Wran- https://github.com/ledger/ledger/wiki/Edit- Text Wran- https://github.com/ledger/ledger/wiki/Edit-
gler ing-Ledger-files-with-TextWrangler gler ing-Ledger-files-with-TextWrangler
Visual Stu- https://marketplace.visualstudio.com/items?item- Visual Stu- https://marketplace.visualstudio.com/items?item-
@ -1288,7 +1300,7 @@ EDITOR SUPPORT
REPORTING BUGS 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) or hledger mail list)
@ -1302,7 +1314,7 @@ COPYRIGHT
SEE ALSO 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- hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time-
dot(5), ledger(1) dot(5), ledger(1)