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.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