Skip to content

Commit bbe91bf

Browse files
jpluscplusmjpluscplusm
committed
Basic README: installation and usage
1 parent 48eadc0 commit bbe91bf

File tree

1 file changed

+162
-0
lines changed

1 file changed

+162
-0
lines changed

‎README.md

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
# beancount-repete
2+
3+
This is a [beancount plugin](https://beancount.github.io/docs/beancount_scripting_plugins.html) that allows specific Transactions to be marked as templates, and repeated on a schedule. The plugin generates synthetic Transactions that mirror their template precisely, with two exceptions:
4+
5+
- the generated Transactions' dates are changed, in line with the set of dates that the template's schedule produces;
6+
- the metadata pair that triggers the plugin (and holds the schedule) is removed. This allows the output of the plugin to be used safely as input for the plugin, without generating unlimited/runaway Transactions.
7+
8+
The schedule can be expressed in any natural language form that the [Recurrent](https://github.com/kvh/recurrent#examples) library supports.
9+
10+
Any Transaction used as a template is removed by the plugin during processing. This allows for schedules such as "monthly from next tuesday" to be used, where the "now" date is taken as being the template Transaction's date.
11+
12+
## Installation
13+
14+
Import the plugin however your beancount repository dictates.
15+
16+
The author currently uses this method, as this plugin is not yet set up as a properly-importable Python package:
17+
18+
```shell
19+
$ grep pythonpath main.beancount
20+
option "insert_pythonpath" "True"
21+
$ grep repete main.beancount
22+
plugin "plugins.beancount-repete.plugin"
23+
$ cd plugins
24+
$ git submodule add https://github.com/jpluscplusm/beancount-repete
25+
Cloning into 'beancount-repete'...
26+
remote: Enumerating objects: 6, done.
27+
remote: Counting objects: 100% (6/6), done.
28+
remote: Compressing objects: 100% (5/5), done.
29+
remote: Total 6 (delta 0), reused 3 (delta 0), pack-reused 0
30+
Receiving objects: 100% (6/6), 12.65 KiB | 762.00 KiB/s, done.
31+
```
32+
33+
### Dependencies
34+
35+
Install the [Recurrent](https://github.com/kvh/recurrent) library. It is available [from PyPI](https://pypi.org/project/recurrent/).
36+
37+
## Usage
38+
39+
Add a metadata pair to any Transaction, with key `repete` and a value holding the natural language expression of a repeating (or one-off!) schedule. The schedule is parsed by the [Recurrent](https://github.com/kvh/recurrent) library, whose [documentation](https://github.com/kvh/recurrent#examples) shows many examples of the text forms that it understands.
40+
41+
### Examples
42+
43+
Given this `example.beancount` input, and the beancount-repete plugin (set up as above):
44+
45+
```shell
46+
$ cat example.beancount
47+
option "insert_pythonpath" "True"
48+
49+
plugin "plugins.beancount-repete.plugin"
50+
plugin "beancount.plugins.auto_accounts"
51+
52+
2022-01-01 ! "Supermarket" "Weekly shop"
53+
repete: "weekly until March 2022"
54+
Assets:Current:Bank:HSBC
55+
Expenses:Groceries:Weekly 75.00 GBP
56+
```
57+
58+
... the following journal is visible to beancount and any of its tools (e.g. Fava, bean-query, etc):
59+
60+
```shell
61+
$ bean-report example.beancount print
62+
2022-01-01 open Assets:Current:Bank:HSBC
63+
2022-01-01 open Expenses:Groceries:Weekly
64+
65+
2022-01-01 ! "Supermarket" "Weekly shop"
66+
Assets:Current:Bank:HSBC -75.00 GBP
67+
Expenses:Groceries:Weekly 75.00 GBP
68+
69+
2022-01-08 ! "Supermarket" "Weekly shop"
70+
Assets:Current:Bank:HSBC -75.00 GBP
71+
Expenses:Groceries:Weekly 75.00 GBP
72+
73+
2022-01-15 ! "Supermarket" "Weekly shop"
74+
Assets:Current:Bank:HSBC -75.00 GBP
75+
Expenses:Groceries:Weekly 75.00 GBP
76+
77+
2022-01-22 ! "Supermarket" "Weekly shop"
78+
Assets:Current:Bank:HSBC -75.00 GBP
79+
Expenses:Groceries:Weekly 75.00 GBP
80+
81+
2022-01-29 ! "Supermarket" "Weekly shop"
82+
Assets:Current:Bank:HSBC -75.00 GBP
83+
Expenses:Groceries:Weekly 75.00 GBP
84+
85+
2022-02-05 ! "Supermarket" "Weekly shop"
86+
Assets:Current:Bank:HSBC -75.00 GBP
87+
Expenses:Groceries:Weekly 75.00 GBP
88+
89+
2022-02-12 ! "Supermarket" "Weekly shop"
90+
Assets:Current:Bank:HSBC -75.00 GBP
91+
Expenses:Groceries:Weekly 75.00 GBP
92+
93+
2022-02-19 ! "Supermarket" "Weekly shop"
94+
Assets:Current:Bank:HSBC -75.00 GBP
95+
Expenses:Groceries:Weekly 75.00 GBP
96+
97+
2022-02-26 ! "Supermarket" "Weekly shop"
98+
Assets:Current:Bank:HSBC -75.00 GBP
99+
Expenses:Groceries:Weekly 75.00 GBP
100+
101+
```
102+
103+
Note that the template Transaction's flag (`!`, here) is persisted across into the synthetic Transactions. It's a good idea to use the "pending" `!` flag, so that Fava and other interfaces don't indicate that this is an entirely normal, concrete Transaction.
104+
105+
The date of the template Transaction is used as the "now" date when interpreting the schedule, which can be useful when the schedule is relative in some way. For example ...
106+
107+
January 1, 2022 was a Saturday. If the above example schedule is modified slightly, we can see the effect:
108+
109+
```shell
110+
$ cat example.beancount
111+
option "insert_pythonpath" "True"
112+
113+
plugin "plugins.beancount-repete.plugin"
114+
plugin "beancount.plugins.auto_accounts"
115+
116+
2022-01-01 ! "Supermarket" "Weekly shop"
117+
repete: "weekly on Tuesday until March 2022"
118+
Assets:Current:Bank:HSBC
119+
Expenses:Groceries:Weekly 75.00 GBP
120+
121+
$ bean-report example.beancount print
122+
2022-01-04 open Assets:Current:Bank:HSBC
123+
2022-01-04 open Expenses:Groceries:Weekly
124+
125+
2022-01-04 ! "Supermarket" "Weekly shop"
126+
Assets:Current:Bank:HSBC -75.00 GBP
127+
Expenses:Groceries:Weekly 75.00 GBP
128+
129+
2022-01-11 ! "Supermarket" "Weekly shop"
130+
Assets:Current:Bank:HSBC -75.00 GBP
131+
Expenses:Groceries:Weekly 75.00 GBP
132+
133+
2022-01-18 ! "Supermarket" "Weekly shop"
134+
Assets:Current:Bank:HSBC -75.00 GBP
135+
Expenses:Groceries:Weekly 75.00 GBP
136+
137+
2022-01-25 ! "Supermarket" "Weekly shop"
138+
Assets:Current:Bank:HSBC -75.00 GBP
139+
Expenses:Groceries:Weekly 75.00 GBP
140+
141+
2022-02-01 ! "Supermarket" "Weekly shop"
142+
Assets:Current:Bank:HSBC -75.00 GBP
143+
Expenses:Groceries:Weekly 75.00 GBP
144+
145+
2022-02-08 ! "Supermarket" "Weekly shop"
146+
Assets:Current:Bank:HSBC -75.00 GBP
147+
Expenses:Groceries:Weekly 75.00 GBP
148+
149+
2022-02-15 ! "Supermarket" "Weekly shop"
150+
Assets:Current:Bank:HSBC -75.00 GBP
151+
Expenses:Groceries:Weekly 75.00 GBP
152+
153+
2022-02-22 ! "Supermarket" "Weekly shop"
154+
Assets:Current:Bank:HSBC -75.00 GBP
155+
Expenses:Groceries:Weekly 75.00 GBP
156+
157+
2022-03-01 ! "Supermarket" "Weekly shop"
158+
Assets:Current:Bank:HSBC -75.00 GBP
159+
Expenses:Groceries:Weekly 75.00 GBP
160+
```
161+
162+
Note that the original template, on 2022-01-01, is not present in this output. This is always true: if a template's schedule would not generate its original date when evaluated, the template Transaction will not be produced.

0 commit comments

Comments
 (0)