Version 0.001
[chaz/homebank2ledger] / bin / homebank2ledger
1 #! perl
2 # ABSTRACT: A tool to convert HomeBank files to Ledger format
3 # PODNAME: homebank2ledger
4
5
6 use warnings;
7 use strict;
8
9 use App::HomeBank2Ledger;
10
11 our $VERSION = '0.001'; # VERSION
12
13 App::HomeBank2Ledger->main(@ARGV);
14
15 __END__
16
17 =pod
18
19 =encoding UTF-8
20
21 =head1 NAME
22
23 homebank2ledger - A tool to convert HomeBank files to Ledger format
24
25 =head1 VERSION
26
27 version 0.001
28
29 =head1 SYNOPSIS
30
31 homebank2ledger --input FILEPATH [--output FILEPATH]
32 [--version|--help|--manual]
33 [--format FORMAT] [--account-width NUM]
34 [--accounts|--no-accounts] [--payees|--no-payees]
35 [--tags|--no-tags] [--commodities|--no-commodities]
36 [--opening-date DATE] [--default-account STR]
37 [--rename-account STR]... [--exclude-account STR]...
38
39 =head1 DESCRIPTION
40
41 C<homebank2ledger> converts L<HomeBank|http://homebank.free.fr/> files to a format usable by
42 L<Ledger|https://www.ledger-cli.org/>. It can also convert directly to the similar
43 L<Beancount|http://furius.ca/beancount/> format.
44
45 This software is B<EXPERIMENTAL>, in early development. Its interface may change without notice.
46
47 I wrote C<homebank2ledger> because I have been maintaining my own personal finances using HomeBank
48 (which is awesome) and I wanted to investigate using plain text accounting programs. It works well
49 enough for my data, but you may be using HomeBank features that I don't so there may be cases this
50 doesn't handle well or at all. Feel free to file a bug report. This script does NOT try to modify
51 the original HomeBank files it converts from, so there won't be any crazy data loss bugs... but no
52 warranty.
53
54 =head2 Features
55
56 =over 4
57
58 =item *
59
60 Converts HomeBank accounts and categories into a typical set of double-entry accounts.
61
62 =item *
63
64 Retains HomeBank metadata, including payees and tags.
65
66 =item *
67
68 Offers some customization of the output ledger, like account renaming.
69
70 =back
71
72 This program is feature-complete in my opinion (well, almost -- see L</CAVEATS>), but if there is
73 anything you think it could do to be even better, feedback is welcome; just file a bug report. Or
74 fork the code and have fun!
75
76 =head2 Use cases
77
78 You can migrate the data you have in HomeBank so you can start maintaining your accounts in Ledger
79 (or Beancount).
80
81 Or if you don't plan to switch completely off of HomeBank, you can continue to maintain your
82 accounts in HomeBank and use this script to also take advantage of the reports Ledger offers.
83
84 =head1 OPTIONS
85
86 =head2 --version
87
88 Print the version and exit.
89
90 Alias: C<-V>
91
92 =head2 --help
93
94 Print help/usage info and exit.
95
96 Alias: C<-h>, C<-?>
97
98 =head2 --manual
99
100 Print the full manual and exit.
101
102 Alias: C<--man>
103
104 =head2 --input FILEPATH
105
106 Specify the path to the HomeBank file to read (must already exist).
107
108 Alias: C<--file>, C<-i>
109
110 =head2 --output FILEPATH
111
112 Specify the path to the Ledger file to write (may not exist yet). If not provided, the formatted
113 ledger will be printed on C<STDOUT>.
114
115 Alias: C<-o>
116
117 =head2 --format STR
118
119 Specify the output file format. If provided, must be one of:
120
121 =over 4
122
123 =item *
124
125 ledger
126
127 =item *
128
129 beancount
130
131 =back
132
133 =head2 --account-width NUM
134
135 Specify the number of characters to reserve for the account column in transactions. Adjusting this
136 can provide prettier formatting of the output.
137
138 Defaults to 40.
139
140 =head2 --accounts
141
142 Enables account declarations.
143
144 Defaults to enabled; use C<--no-accounts> to disable.
145
146 =head2 --payees
147
148 Enables payee declarations.
149
150 Defaults to enabled; use C<--no-payees> to disable.
151
152 =head2 --tags
153
154 Enables tag declarations.
155
156 Defaults to enabled; use C<--no-tags> to disable.
157
158 =head2 --commodities
159
160 Enables commodity declarations.
161
162 Defaults to enabled; use C<--no-commodities> to disable.
163
164 =head2 --opening-date DATE
165
166 Specify the opening date for the "opening balances" transaction. This transaction is created (if
167 needed) to support HomeBank's ability to configure accounts with opening balances.
168
169 Date must be in the form "YYYY-MM-DD". Defaults to the date of the first transaction.
170
171 =head2 --default-account STR
172
173 Specify the account to use for one-sided transactions (if any). Defaults to "Expenses:No Category".
174
175 A default account may be necessary because with Ledger all transactions are double-entry.
176
177 =head2 --rename-account STR
178
179 Specifies a mapping for renaming accounts in the output. By default C<homebank2ledger> tries to come
180 up with sensible account names (based on your HomeBank accounts and categories) that fit into five
181 root accounts:
182
183 =over 4
184
185 =item *
186
187 Assets
188
189 =item *
190
191 Liabilities
192
193 =item *
194
195 Equity
196
197 =item *
198
199 Income
200
201 =item *
202
203 Expenses
204
205 =back
206
207 The value of the argument must be of the form "REGEXP=REPLACEMENT". See L</EXAMPLES>.
208
209 Can be repeated to rename multiple accounts.
210
211 =head2 --exclude-account STR
212
213 Specifies an account that will not be included in the output. All transactions related to this
214 account will be skipped.
215
216 Can be repeated to exclude multiple accounts.
217
218 =head1 EXAMPLES
219
220 =head2 Basic usage
221
222 # Convert homebank.xhb to a Ledger-compatible file:
223 homebank2ledger path/to/homebank.xhb -o ledger.dat
224
225 # Run the Ledger balance report:
226 ledger -f ledger.dat balance
227
228 You can also combine this into one command:
229
230 homebank2ledger path/to/homebank.xhb | ledger -f - balance
231
232 =head2 Account renaming
233
234 With the L</"--rename-account STR"> argument, you have some control over the resulting account
235 structure. This may be useful in cases where the organization imposed (or encouraged) by HomeBank
236 doesn't necessarily line up with an ideal double-entry structure.
237
238 homebank2ledger path/to/homebank.xhb -o ledger.dat \
239 --rename-account '^Assets:Credit Union Savings$=Assets:Bank:Credit Union:Savings' \
240 --rename-account '^Assets:Credit Union Checking$=Assets:Bank:Credit Union:Checking'
241
242 Multiple accounts can be renamed at the same time because the first part of the mapping is a regular
243 expression. The above example could be written like this:
244
245 homebank2ledger path/to/homebank.xhb -o ledger.dat \
246 --rename-account '^Assets:Credit Union =Assets:Bank:Credit Union:'
247
248 You can also merge accounts by simple renaming multiple accounts to the same name:
249
250 homebank2ledger path/to/homebank.xhb -o ledger.dat \
251 --rename-account '^Liabilities:Chase VISA$=Liabilities:All Credit Cards' \
252 --rename-account '^Liabilities:Amex$=Liabilities:All Credit Cards'
253
254 If you need to do anything more complicated, of course you can edit the output after converting;
255 it's just plain text.
256
257 =head2 Beancount
258
259 # Convert homebank.xhb to a Beancount-compatible file:
260 homebank2ledger path/to/homebank.xhb -f beancount -o ledger.beancount
261
262 # Run the balances report:
263 bean-report ledger.beancount balances
264
265 =head1 CAVEATS
266
267 =over 4
268
269 =item *
270
271 I didn't intend to make this a releasable robust product, so it's lacking tests.
272
273 =item *
274
275 Budgets and scheduled transactions are not (yet) converted.
276
277 =item *
278
279 There are some minor formatting tweaks I will make (e.g. consolidate transaction tags and payees)
280
281 =back
282
283 =head1 BUGS
284
285 Please report any bugs or feature requests on the bugtracker website
286 L<https://github.com/chazmcgarvey/homebank2ledger/issues>
287
288 When submitting a bug or request, please include a test-file or a
289 patch to an existing test-file that illustrates the bug or desired
290 feature.
291
292 =head1 AUTHOR
293
294 Charles McGarvey <chazmcgarvey@brokenzipper.com>
295
296 =head1 COPYRIGHT AND LICENSE
297
298 This software is Copyright (c) 2019 by Charles McGarvey.
299
300 This is free software, licensed under:
301
302 The MIT (X11) License
303
304 =cut
This page took 0.051246 seconds and 4 git commands to generate.