| 1 |
rewrite |
| 2 |
|
| 3 |
Print all transactions, rewriting the postings of matched transactions. |
| 4 |
For now the only rewrite available is adding new postings, like print |
| 5 |
--auto. |
| 6 |
|
| 7 |
Flags: |
| 8 |
--add-posting='ACCT AMTEXPR' add a posting to ACCT, which may be |
| 9 |
parenthesised. AMTEXPR is either a literal |
| 10 |
amount, or *N which means the transaction's |
| 11 |
first matched amount multiplied by N (a |
| 12 |
decimal number). Two spaces separate ACCT |
| 13 |
and AMTEXPR. |
| 14 |
--diff generate diff suitable as an input for |
| 15 |
patch tool |
| 16 |
|
| 17 |
This is a start at a generic rewriter of transaction entries. It reads |
| 18 |
the default journal and prints the transactions, like print, but adds |
| 19 |
one or more specified postings to any transactions matching QUERY. The |
| 20 |
posting amounts can be fixed, or a multiplier of the existing |
| 21 |
transaction's first posting amount. |
| 22 |
|
| 23 |
Examples: |
| 24 |
|
| 25 |
$ hledger-rewrite.hs ^income --add-posting '(liabilities:tax) *.33 ; income tax' --add-posting '(reserve:gifts) $100' |
| 26 |
$ hledger-rewrite.hs expenses:gifts --add-posting '(reserve:gifts) *-1"' |
| 27 |
$ hledger-rewrite.hs -f rewrites.hledger |
| 28 |
|
| 29 |
rewrites.hledger may consist of entries like: |
| 30 |
|
| 31 |
= ^income amt:<0 date:2017 |
| 32 |
(liabilities:tax) *0.33 ; tax on income |
| 33 |
(reserve:grocery) *0.25 ; reserve 25% for grocery |
| 34 |
(reserve:) *0.25 ; reserve 25% for grocery |
| 35 |
|
| 36 |
Note the single quotes to protect the dollar sign from bash, and the two |
| 37 |
spaces between account and amount. |
| 38 |
|
| 39 |
More: |
| 40 |
|
| 41 |
$ hledger rewrite [QUERY] --add-posting "ACCT AMTEXPR" ... |
| 42 |
$ hledger rewrite ^income --add-posting '(liabilities:tax) *.33' |
| 43 |
$ hledger rewrite expenses:gifts --add-posting '(budget:gifts) *-1"' |
| 44 |
$ hledger rewrite ^income --add-posting '(budget:foreign currency) *0.25 JPY; diversify' |
| 45 |
|
| 46 |
Argument for --add-posting option is a usual posting of transaction with |
| 47 |
an exception for amount specification. More precisely, you can use '*' |
| 48 |
(star symbol) before the amount to indicate that that this is a factor |
| 49 |
for an amount of original matched posting. If the amount includes a |
| 50 |
commodity name, the new posting amount will be in the new commodity; |
| 51 |
otherwise, it will be in the matched posting amount's commodity. |
| 52 |
|
| 53 |
Re-write rules in a file |
| 54 |
|
| 55 |
During the run this tool will execute so called "Automated Transactions" |
| 56 |
found in any journal it process. I.e instead of specifying this |
| 57 |
operations in command line you can put them in a journal file. |
| 58 |
|
| 59 |
$ rewrite-rules.journal |
| 60 |
|
| 61 |
Make contents look like this: |
| 62 |
|
| 63 |
= ^income |
| 64 |
(liabilities:tax) *.33 |
| 65 |
|
| 66 |
= expenses:gifts |
| 67 |
budget:gifts *-1 |
| 68 |
assets:budget *1 |
| 69 |
|
| 70 |
Note that '=' (equality symbol) that is used instead of date in |
| 71 |
transactions you usually write. It indicates the query by which you want |
| 72 |
to match the posting to add new ones. |
| 73 |
|
| 74 |
$ hledger rewrite -f input.journal -f rewrite-rules.journal > rewritten-tidy-output.journal |
| 75 |
|
| 76 |
This is something similar to the commands pipeline: |
| 77 |
|
| 78 |
$ hledger rewrite -f input.journal '^income' --add-posting '(liabilities:tax) *.33' \ |
| 79 |
| hledger rewrite -f - expenses:gifts --add-posting 'budget:gifts *-1' \ |
| 80 |
--add-posting 'assets:budget *1' \ |
| 81 |
> rewritten-tidy-output.journal |
| 82 |
|
| 83 |
It is important to understand that relative order of such entries in |
| 84 |
journal is important. You can re-use result of previously added |
| 85 |
postings. |
| 86 |
|
| 87 |
Diff output format |
| 88 |
|
| 89 |
To use this tool for batch modification of your journal files you may |
| 90 |
find useful output in form of unified diff. |
| 91 |
|
| 92 |
$ hledger rewrite --diff -f examples/sample.journal '^income' --add-posting '(liabilities:tax) *.33' |
| 93 |
|
| 94 |
Output might look like: |
| 95 |
|
| 96 |
--- /tmp/examples/sample.journal |
| 97 |
+++ /tmp/examples/sample.journal |
| 98 |
@@ -18,3 +18,4 @@ |
| 99 |
2008/01/01 income |
| 100 |
- assets:bank:checking $1 |
| 101 |
+ assets:bank:checking $1 |
| 102 |
income:salary |
| 103 |
+ (liabilities:tax) 0 |
| 104 |
@@ -22,3 +23,4 @@ |
| 105 |
2008/06/01 gift |
| 106 |
- assets:bank:checking $1 |
| 107 |
+ assets:bank:checking $1 |
| 108 |
income:gifts |
| 109 |
+ (liabilities:tax) 0 |
| 110 |
|
| 111 |
If you'll pass this through patch tool you'll get transactions |
| 112 |
containing the posting that matches your query be updated. Note that |
| 113 |
multiple files might be update according to list of input files |
| 114 |
specified via --file options and include directives inside of these |
| 115 |
files. |
| 116 |
|
| 117 |
Be careful. Whole transaction being re-formatted in a style of output |
| 118 |
from hledger print. |
| 119 |
|
| 120 |
See also: |
| 121 |
|
| 122 |
https://github.com/simonmichael/hledger/issues/99 |
| 123 |
|
| 124 |
rewrite vs. print --auto |
| 125 |
|
| 126 |
This command predates print --auto, and currently does much the same |
| 127 |
thing, but with these differences: |
| 128 |
|
| 129 |
- with multiple files, rewrite lets rules in any file affect all other |
| 130 |
files. print --auto uses standard directive scoping; rules affect only |
| 131 |
child files. |
| 132 |
|
| 133 |
- rewrite's query limits which transactions can be rewritten; all are |
| 134 |
printed. print --auto's query limits which transactions are printed. |
| 135 |
|
| 136 |
- rewrite applies rules specified on command line or in the journal. |
| 137 |
print --auto applies rules specified in the journal. |