Dogcows Code - chaz/homebank2ledger/blob - 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.004'; # 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.004
  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]
  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 --rename-account STR
 171
 172 Specifies a mapping for renaming accounts in the output. By default C<homebank2ledger> tries to come
 173 up with sensible account names (based on your HomeBank accounts and categories) that fit into five
 174 root accounts:
 175
 176 =over 4
 177
 178 =item *
 179
 180 Assets
 181
 182 =item *
 183
 184 Liabilities
 185
 186 =item *
 187
 188 Equity
 189
 190 =item *
 191
 192 Income
 193
 194 =item *
 195
 196 Expenses
 197
 198 =back
 199
 200 The value of the argument must be of the form "REGEXP=REPLACEMENT". See L</EXAMPLES>.
 201
 202 Can be repeated to rename multiple accounts.
 203
 204 =head2 --exclude-account STR
 205
 206 Specifies an account that will not be included in the output. All transactions related to this
 207 account will be skipped.
 208
 209 Can be repeated to exclude multiple accounts.
 210
 211 =head1 EXAMPLES
 212
 213 =head2 Basic usage
 214
 215     # Convert homebank.xhb to a Ledger-compatible file:
 216     homebank2ledger path/to/homebank.xhb -o ledger.dat
 217
 218     # Run the Ledger balance report:
 219     ledger -f ledger.dat balance
 220
 221 You can also combine this into one command:
 222
 223     homebank2ledger path/to/homebank.xhb | ledger -f - balance
 224
 225 =head2 Account renaming
 226
 227 With the L</"--rename-account STR"> argument, you have some control over the resulting account
 228 structure. This may be useful in cases where the organization imposed (or encouraged) by HomeBank
 229 doesn't necessarily line up with an ideal double-entry structure.
 230
 231     homebank2ledger path/to/homebank.xhb -o ledger.dat \
 232         --rename-account '^Assets:Credit Union Savings$=Assets:Bank:Credit Union:Savings' \
 233         --rename-account '^Assets:Credit Union Checking$=Assets:Bank:Credit Union:Checking'
 234
 235 Multiple accounts can be renamed at the same time because the first part of the mapping is a regular
 236 expression. The above example could be written like this:
 237
 238     homebank2ledger path/to/homebank.xhb -o ledger.dat \
 239         --rename-account '^Assets:Credit Union =Assets:Bank:Credit Union:'
 240
 241 You can also merge accounts by simple renaming multiple accounts to the same name:
 242
 243     homebank2ledger path/to/homebank.xhb -o ledger.dat \
 244         --rename-account '^Liabilities:Chase VISA$=Liabilities:All Credit Cards' \
 245         --rename-account '^Liabilities:Amex$=Liabilities:All Credit Cards'
 246
 247 If you need to do anything more complicated, of course you can edit the output after converting;
 248 it's just plain text.
 249
 250 =head2 Beancount
 251
 252     # Convert homebank.xhb to a Beancount-compatible file:
 253     homebank2ledger path/to/homebank.xhb -f beancount -o ledger.beancount
 254
 255     # Run the balances report:
 256     bean-report ledger.beancount balances
 257
 258 =head1 CAVEATS
 259
 260 =over 4
 261
 262 =item *
 263
 264 I didn't intend to make this a releasable robust product, so it's lacking tests.
 265
 266 =item *
 267
 268 Budgets and scheduled transactions are not (yet) converted.
 269
 270 =item *
 271
 272 There are some minor formatting tweaks I will make (e.g. consolidate transaction tags and payees)
 273
 274 =back
 275
 276 =head1 BUGS
 277
 278 Please report any bugs or feature requests on the bugtracker website
 279 L<https://github.com/chazmcgarvey/homebank2ledger/issues>
 280
 281 When submitting a bug or request, please include a test-file or a
 282 patch to an existing test-file that illustrates the bug or desired
 283 feature.
 284
 285 =head1 AUTHOR
 286
 287 Charles McGarvey <chazmcgarvey@brokenzipper.com>
 288
 289 =head1 COPYRIGHT AND LICENSE
 290
 291 This software is Copyright (c) 2019 by Charles McGarvey.
 292
 293 This is free software, licensed under:
 294
 295   The MIT (X11) License
 296
 297 =cut