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