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