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 =head1 SYNOPSIS
   6
   7     homebank2ledger --input FILEPATH [--output FILEPATH] [--format FORMAT]
   8                     [--version|--help|--manual] [--account-width NUM]
   9                     [--accounts|--no-accounts] [--payees|--no-payees]
  10                     [--tags|--no-tags] [--commodities|--no-commodities]
  11                     [--opening-date DATE] [--default-account STR]
  12                     [--rename-account STR]... [--exclude-account STR]...
  13
  14 =head1 DESCRIPTION
  15
  16 C<homebank2ledger> converts L<HomeBank|http://homebank.free.fr/> files to a format usable by
  17 L<Ledger|https://www.ledger-cli.org/>. It can also convert directly to the similar
  18 L<Beancount|http://furius.ca/beancount/> format.
  19
  20 This software is B<EXPERIMENTAL>, in early development. Its interface may change without notice.
  21
  22 I wrote C<homebank2ledger> because I have been maintaining my own personal finances using HomeBank
  23 (which is awesome) and I wanted to investigate using plain text accounting programs. It works well
  24 enough for my data, but you may be using HomeBank features that I don't so there may be cases this
  25 doesn't handle well or at all. Feel free to file a bug report. This script does NOT try to modify
  26 the original HomeBank files it converts from, so there won't be any crazy data loss bugs... but no
  27 warranty.
  28
  29 =head2 Features
  30
  31 =for :list
  32 * Converts HomeBank accounts and categories into a typical set of double-entry accounts.
  33 * Retains HomeBank metadata, including payees and tags.
  34 * Offers some customization of the output ledger, like account renaming.
  35
  36 This program is feature-complete in my opinion (well, almost -- see L</CAVEATS>), but if there is
  37 anything you think it could do to be even better, feedback is welcome; just file a bug report. Or
  38 fork the code and have fun!
  39
  40 =head2 Use cases
  41
  42 You can migrate the data you have in HomeBank so you can start maintaining your accounts in Ledger
  43 (or Beancount).
  44
  45 Or if you don't plan to switch completely off of HomeBank, you can continue to maintain your
  46 accounts in HomeBank and use this script to also take advantage of the reports Ledger offers.
  47
  48 =head1 OPTIONS
  49
  50 =head2 --version
  51
  52 Print the version and exit.
  53
  54 Alias: C<-V>
  55
  56 =head2 --help
  57
  58 Print help/usage info and exit.
  59
  60 Alias: C<-h>, C<-?>
  61
  62 =head2 --manual
  63
  64 Print the full manual and exit.
  65
  66 Alias: C<--man>
  67
  68 =head2 --input FILEPATH
  69
  70 Specify the path to the HomeBank file to read (must already exist).
  71
  72 Alias: C<--file>, C<-i>
  73
  74 =head2 --output FILEPATH
  75
  76 Specify the path to the Ledger file to write (may not exist yet). If not provided, the formatted
  77 ledger will be printed on C<STDOUT>.
  78
  79 Alias: C<-o>
  80
  81 =head2 --format STR
  82
  83 Specify the output file format. If provided, must be one of:
  84
  85 =for :list
  86 * ledger
  87 * beancount
  88
  89 =head2 --account-width NUM
  90
  91 Specify the number of characters to reserve for the account column in transactions. Adjusting this
  92 can provide prettier formatting of the output.
  93
  94 Defaults to 40.
  95
  96 =head2 --accounts
  97
  98 Enables account declarations.
  99
 100 Defaults to enabled; use C<--no-accounts> to disable.
 101
 102 =head2 --payees
 103
 104 Enables payee declarations.
 105
 106 Defaults to enabled; use C<--no-payees> to disable.
 107
 108 =head2 --tags
 109
 110 Enables tag declarations.
 111
 112 Defaults to enabled; use C<--no-tags> to disable.
 113
 114 =head2 --commodities
 115
 116 Enables commodity declarations.
 117
 118 Defaults to enabled; use C<--no-commodities> to disable.
 119
 120 =head2 --opening-date DATE
 121
 122 Specify the opening date for the "opening balances" transaction. This transaction is created (if
 123 needed) to support HomeBank's ability to configure accounts with opening balances.
 124
 125 Date must be in the form "YYYY-MM-DD". Defaults to the date of the first transaction.
 126
 127 =head2 --default-account STR
 128
 129 Specify the account to use for one-sided transactions (if any). Defaults to "Expenses:No Category".
 130
 131 A default account may be necessary because with Ledger all transactions are double-entry.
 132
 133 =head2 --rename-account STR
 134
 135 Specifies a mapping for renaming accounts in the output. By default C<homebank2ledger> tries to come
 136 up with sensible account names (based on your HomeBank accounts and categories) that fit into five
 137 root accounts:
 138
 139 =for :list
 140 * Assets
 141 * Liabilities
 142 * Equity
 143 * Income
 144 * Expenses
 145
 146 The value of the argument must be of the form "REGEXP=REPLACEMENT". See L</EXAMPLES>.
 147
 148 Can be repeated to rename multiple accounts.
 149
 150 =head2 --exclude-account STR
 151
 152 Specifies an account that will not be included in the output. All transactions related to this
 153 account will be skipped.
 154
 155 Can be repeated to exclude multiple accounts.
 156
 157 =head1 EXAMPLES
 158
 159 =head2 Basic usage
 160
 161     # Convert homebank.xhb to a Ledger-compatible file:
 162     homebank2ledger path/to/homebank.xhb -o ledger.dat
 163
 164     # Run the Ledger balance report:
 165     ledger -f ledger.dat balance
 166
 167 You can also combine this into one command:
 168
 169     homebank2ledger path/to/homebank.xhb | ledger -f - balance
 170
 171 =head2 Account renaming
 172
 173 With the L</"--rename-account STR"> argument, you have some control over the resulting account
 174 structure. This may be useful in cases where the organization imposed (or encouraged) by HomeBank
 175 doesn't necessarily line up with an ideal double-entry structure.
 176
 177     homebank2ledger path/to/homebank.xhb -o ledger.dat \
 178         --rename-account '^Assets:Credit Union Savings$=Assets:Bank:Credit Union:Savings' \
 179         --rename-account '^Assets:Credit Union Checking$=Assets:Bank:Credit Union:Checking'
 180
 181 Multiple accounts can be renamed at the same time because the first part of the mapping is a regular
 182 expression. The above example could be written like this:
 183
 184     homebank2ledger path/to/homebank.xhb -o ledger.dat \
 185         --rename-account '^Assets:Credit Union =Assets:Bank:Credit Union:'
 186
 187 You can also merge accounts by simple renaming multiple accounts to the same name:
 188
 189     homebank2ledger path/to/homebank.xhb -o ledger.dat \
 190         --rename-account '^Liabilities:Chase VISA$=Liabilities:All Credit Cards' \
 191         --rename-account '^Liabilities:Amex$=Liabilities:All Credit Cards'
 192
 193 If you need to do anything more complicated, of course you can edit the output after converting;
 194 it's just plain text.
 195
 196 =head2 Beancount
 197
 198     # Convert homebank.xhb to a Beancount-compatible file:
 199     homebank2ledger path/to/homebank.xhb -f beancount -o ledger.beancount
 200
 201     # Run the balances report:
 202     bean-report ledger.beancount balances
 203
 204 =head1 CAVEATS
 205
 206 =for :list
 207 * I didn't intend to make this a releasable robust product, so it's lacking tests.
 208 * Budgets and scheduled transactions are not (yet) converted.
 209 * There are some minor formatting tweaks I will make (e.g. consolidate transaction tags and payees)
 210
 211 =cut
 212
 213 use warnings;
 214 use strict;
 215
 216 use App::HomeBank2Ledger;
 217
 218 our $VERSION = '9999.999'; # VERSION
 219
 220 App::HomeBank2Ledger->main(@ARGV);