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