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