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