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