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]
  12                     [--rename-account STR]... [--exclude-account STR]...
  13
  14 =head1 DESCRIPTION
  15
  16 F<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 F<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 INSTALL
  49
  50 There are several ways to install F<homebank2ledger> to your system.
  51
  52 =head2 using cpanm
  53
  54 You can install F<homebank2ledger> using L<cpanm>. If you have a local perl (plenv, perlbrew, etc.),
  55 you can just do:
  56
  57     cpanm App::Homebank2Ledger
  58
  59 to install the F<homebank2ledger> executable and its dependencies. The executable will be installed
  60 to your perl's bin path, like F<~/perl5/perlbrew/bin/homebank2ledger>.
  61
  62 If you're installing to your system perl, you can do:
  63
  64     cpanm --sudo App::Homebank2Ledger
  65
  66 to install the F<homebank2ledger> executable to a system directory, like
  67 F</usr/local/bin/homebank2ledger> (depending on your perl).
  68
  69 =head2 Downloading just the executable
  70
  71 You may also choose to download F<homebank2ledger> as a single executable, like this:
  72
  73     curl -OL https://raw.githubusercontent.com/chazmcgarvey/homebank2ledger/solo/homebank2ledger
  74     chmod +x homebank2ledger
  75
  76 =head2 For developers
  77
  78 If you're a developer and want to hack on the source, clone the repository and pull the
  79 dependencies:
  80
  81     git clone https://github.com/chazmcgarvey/homebank2ledger.git
  82     cd homebank2ledger
  83     make bootstrap      # installs dependencies; requires cpanm
  84
  85 =head1 OPTIONS
  86
  87 =head2 --version
  88
  89 Print the version and exit.
  90
  91 Alias: C<-V>
  92
  93 =head2 --help
  94
  95 Print help/usage info and exit.
  96
  97 Alias: C<-h>, C<-?>
  98
  99 =head2 --manual
 100
 101 Print the full manual and exit.
 102
 103 Alias: C<--man>
 104
 105 =head2 --input FILEPATH
 106
 107 Specify the path to the HomeBank file to read (must already exist).
 108
 109 Alias: C<--file>, C<-i>
 110
 111 =head2 --output FILEPATH
 112
 113 Specify the path to the Ledger file to write (may not exist yet). If not provided, the formatted
 114 ledger will be printed on C<STDOUT>.
 115
 116 Alias: C<-o>
 117
 118 =head2 --format STR
 119
 120 Specify the output file format. If provided, must be one of:
 121
 122 =for :list
 123 * ledger
 124 * beancount
 125
 126 =head2 --account-width NUM
 127
 128 Specify the number of characters to reserve for the account column in transactions. Adjusting this
 129 can provide prettier formatting of the output.
 130
 131 Defaults to 40.
 132
 133 =head2 --accounts
 134
 135 Enables account declarations.
 136
 137 Defaults to enabled; use C<--no-accounts> to disable.
 138
 139 =head2 --payees
 140
 141 Enables payee declarations.
 142
 143 Defaults to enabled; use C<--no-payees> to disable.
 144
 145 =head2 --tags
 146
 147 Enables tag declarations.
 148
 149 Defaults to enabled; use C<--no-tags> to disable.
 150
 151 =head2 --commodities
 152
 153 Enables commodity declarations.
 154
 155 Defaults to enabled; use C<--no-commodities> to disable.
 156
 157 =head2 --budget
 158
 159 Enables budget transactions.
 160
 161 Budget transactions are only supported by the Ledger format (for now). This option is silently
 162 ignored otherwise.
 163
 164 Defaults to enabled; use C<--no-budget> to disable.
 165
 166 =head2 --opening-date DATE
 167
 168 Specify the opening date for the "opening balances" transaction. This transaction is created (if
 169 needed) to support HomeBank's ability to configure accounts with opening balances.
 170
 171 Date must be in the form "YYYY-MM-DD". Defaults to the date of the first transaction.
 172
 173 =head2 --rename-account STR
 174
 175 Specifies a mapping for renaming accounts in the output. By default F<homebank2ledger> tries to come
 176 up with sensible account names (based on your HomeBank accounts and categories) that fit into five
 177 root accounts:
 178
 179 =for :list
 180 * Assets
 181 * Liabilities
 182 * Equity
 183 * Income
 184 * Expenses
 185
 186 The value of the argument must be of the form "REGEXP=REPLACEMENT". See L</EXAMPLES>.
 187
 188 Can be repeated to rename multiple accounts.
 189
 190 =head2 --exclude-account STR
 191
 192 Specifies an account that will not be included in the output. All transactions related to this
 193 account will be skipped.
 194
 195 Can be repeated to exclude multiple accounts.
 196
 197 =head1 EXAMPLES
 198
 199 =head2 Basic usage
 200
 201     # Convert homebank.xhb to a Ledger-compatible file:
 202     homebank2ledger path/to/homebank.xhb -o ledger.dat
 203
 204     # Run the Ledger balance report:
 205     ledger -f ledger.dat balance
 206
 207 You can also combine this into one command:
 208
 209     homebank2ledger path/to/homebank.xhb | ledger -f - balance
 210
 211 =head2 Account renaming
 212
 213 With the L</"--rename-account STR"> argument, you have some control over the resulting account
 214 structure. This may be useful in cases where the organization imposed (or encouraged) by HomeBank
 215 doesn't necessarily line up with an ideal double-entry structure.
 216
 217     homebank2ledger path/to/homebank.xhb -o ledger.dat \
 218         --rename-account '^Assets:Credit Union Savings$=Assets:Bank:Credit Union:Savings' \
 219         --rename-account '^Assets:Credit Union Checking$=Assets:Bank:Credit Union:Checking'
 220
 221 Multiple accounts can be renamed at the same time because the first part of the mapping is a regular
 222 expression. The above example could be written like this:
 223
 224     homebank2ledger path/to/homebank.xhb -o ledger.dat \
 225         --rename-account '^Assets:Credit Union =Assets:Bank:Credit Union:'
 226
 227 You can also merge accounts by simple renaming multiple accounts to the same name:
 228
 229     homebank2ledger path/to/homebank.xhb -o ledger.dat \
 230         --rename-account '^Liabilities:Chase VISA$=Liabilities:All Credit Cards' \
 231         --rename-account '^Liabilities:Amex$=Liabilities:All Credit Cards'
 232
 233 If you need to do anything more complicated, of course you can edit the output after converting;
 234 it's just plain text.
 235
 236 =head2 Beancount
 237
 238     # Convert homebank.xhb to a Beancount-compatible file:
 239     homebank2ledger path/to/homebank.xhb -f beancount -o ledger.beancount
 240
 241     # Run the balances report:
 242     bean-report ledger.beancount balances
 243
 244 =head1 CAVEATS
 245
 246 =for :list
 247 * I didn't intend to make this a releasable robust product, so it's lacking tests.
 248 * Scheduled transactions are not (yet) converted.
 249 * There are some minor formatting tweaks I will make (e.g. consolidate transaction tags and payees)
 250
 251 =cut
 252
 253 # FATPACK - Do not remove this line.
 254
 255 use warnings;
 256 use strict;
 257
 258 use App::HomeBank2Ledger;
 259
 260 our $VERSION = '9999.999'; # VERSION
 261
 262 App::HomeBank2Ledger->main(@ARGV);