Version 0.002

[chaz/homebank2ledger] / README

diff --git a/README b/README
index edf80f67b68867f093deecf76776401eb0fd5934..8bb567f67b4fd9c93edc38789f01d56850e331a5 100644 (file)
--- a/README
+++ b/README
@@ -1,52 +1,241 @@
 NAME
 
 NAME
 

-    App::HomeBank2Ledger - A tool to convert HomeBank files to Ledger
-    format
+    homebank2ledger - A tool to convert HomeBank files to Ledger format

 
 VERSION
 
 
 VERSION
 

-    version 0.001
+    version 0.002

 
 SYNOPSIS
 
 
 SYNOPSIS
 

-        App::HomeBank2Ledger->main(@args);
+        homebank2ledger --input FILEPATH [--output FILEPATH] [--format FORMAT]
+                        [--version|--help|--manual] [--account-width NUM]
+                        [--accounts|--no-accounts] [--payees|--no-payees]
+                        [--tags|--no-tags] [--commodities|--no-commodities]
+                        [--opening-date DATE] [--default-account STR]
+                        [--rename-account STR]... [--exclude-account STR]...

 
 DESCRIPTION
 
 
 DESCRIPTION
 

-    This module is part of the homebank2ledger script.
+    homebank2ledger converts HomeBank <http://homebank.free.fr/> files to a
+    format usable by Ledger <https://www.ledger-cli.org/>. It can also
+    convert directly to the similar Beancount <http://furius.ca/beancount/>
+    format.

 
 

-METHODS
+    This software is EXPERIMENTAL, in early development. Its interface may
+    change without notice.

 
 

- main
+    I wrote homebank2ledger because I have been maintaining my own personal
+    finances using HomeBank (which is awesome) and I wanted to investigate
+    using plain text accounting programs. It works well enough for my data,
+    but you may be using HomeBank features that I don't so there may be
+    cases this doesn't handle well or at all. Feel free to file a bug
+    report. This script does NOT try to modify the original HomeBank files
+    it converts from, so there won't be any crazy data loss bugs... but no
+    warranty.

 
 

-        App::HomeBank2Ledger->main(@args);
+ Features

 
 

-    Run the script and exit; does not return.
+      * Converts HomeBank accounts and categories into a typical set of
+      double-entry accounts.

 
 

- formatter
+      * Retains HomeBank metadata, including payees and tags.

 
 

-        $formatter = $app->formatter($homebank, $opts);
+      * Offers some customization of the output ledger, like account
+      renaming.

 
 

-    Generate a App::HomeBank2Ledger::Formatter.
+    This program is feature-complete in my opinion (well, almost -- see
+    "CAVEATS"), but if there is anything you think it could do to be even
+    better, feedback is welcome; just file a bug report. Or fork the code
+    and have fun!

 
 

- convert_homebank_to_ledger
+ Use cases

 
 

-        my $ledger = $app->convert_homebank_to_ledger($homebank, $opts);
+    You can migrate the data you have in HomeBank so you can start
+    maintaining your accounts in Ledger (or Beancount).

 
 

-    Converts a File::HomeBank to a App::HomeBank2Ledger::Ledger.
+    Or if you don't plan to switch completely off of HomeBank, you can
+    continue to maintain your accounts in HomeBank and use this script to
+    also take advantage of the reports Ledger offers.

 
 

- print_to_file
+OPTIONS

 
 

-        $app->print_to_file($str);
-        $app->print_to_file($str, $filepath);
+ --version

 
 

-    Print a string to a file (or STDOUT).
+    Print the version and exit.

 
 

- parse_args
+    Alias: -V

 
 

-        $opts = $app->parse_args(@args);
+ --help

 
 

-    Parse command-line arguments.
+    Print help/usage info and exit.
+
+    Alias: -h, -?
+
+ --manual
+
+    Print the full manual and exit.
+
+    Alias: --man
+
+ --input FILEPATH
+
+    Specify the path to the HomeBank file to read (must already exist).
+
+    Alias: --file, -i
+
+ --output FILEPATH
+
+    Specify the path to the Ledger file to write (may not exist yet). If
+    not provided, the formatted ledger will be printed on STDOUT.
+
+    Alias: -o
+
+ --format STR
+
+    Specify the output file format. If provided, must be one of:
+
+      * ledger
+
+      * beancount
+
+ --account-width NUM
+
+    Specify the number of characters to reserve for the account column in
+    transactions. Adjusting this can provide prettier formatting of the
+    output.
+
+    Defaults to 40.
+
+ --accounts
+
+    Enables account declarations.
+
+    Defaults to enabled; use --no-accounts to disable.
+
+ --payees
+
+    Enables payee declarations.
+
+    Defaults to enabled; use --no-payees to disable.
+
+ --tags
+
+    Enables tag declarations.
+
+    Defaults to enabled; use --no-tags to disable.
+
+ --commodities
+
+    Enables commodity declarations.
+
+    Defaults to enabled; use --no-commodities to disable.
+
+ --opening-date DATE
+
+    Specify the opening date for the "opening balances" transaction. This
+    transaction is created (if needed) to support HomeBank's ability to
+    configure accounts with opening balances.
+
+    Date must be in the form "YYYY-MM-DD". Defaults to the date of the
+    first transaction.
+
+ --default-account STR
+
+    Specify the account to use for one-sided transactions (if any).
+    Defaults to "Expenses:No Category".
+
+    A default account may be necessary because with Ledger all transactions
+    are double-entry.
+
+ --rename-account STR
+
+    Specifies a mapping for renaming accounts in the output. By default
+    homebank2ledger tries to come up with sensible account names (based on
+    your HomeBank accounts and categories) that fit into five root
+    accounts:
+
+      * Assets
+
+      * Liabilities
+
+      * Equity
+
+      * Income
+
+      * Expenses
+
+    The value of the argument must be of the form "REGEXP=REPLACEMENT". See
+    "EXAMPLES".
+
+    Can be repeated to rename multiple accounts.
+
+ --exclude-account STR
+
+    Specifies an account that will not be included in the output. All
+    transactions related to this account will be skipped.
+
+    Can be repeated to exclude multiple accounts.
+
+EXAMPLES
+
+ Basic usage
+
+        # Convert homebank.xhb to a Ledger-compatible file:
+        homebank2ledger path/to/homebank.xhb -o ledger.dat
+    
+        # Run the Ledger balance report:
+        ledger -f ledger.dat balance
+
+    You can also combine this into one command:
+
+        homebank2ledger path/to/homebank.xhb | ledger -f - balance
+
+ Account renaming
+
+    With the "--rename-account STR" argument, you have some control over
+    the resulting account structure. This may be useful in cases where the
+    organization imposed (or encouraged) by HomeBank doesn't necessarily
+    line up with an ideal double-entry structure.
+
+        homebank2ledger path/to/homebank.xhb -o ledger.dat \
+            --rename-account '^Assets:Credit Union Savings$=Assets:Bank:Credit Union:Savings' \
+            --rename-account '^Assets:Credit Union Checking$=Assets:Bank:Credit Union:Checking'
+
+    Multiple accounts can be renamed at the same time because the first
+    part of the mapping is a regular expression. The above example could be
+    written like this:
+
+        homebank2ledger path/to/homebank.xhb -o ledger.dat \
+            --rename-account '^Assets:Credit Union =Assets:Bank:Credit Union:'
+
+    You can also merge accounts by simple renaming multiple accounts to the
+    same name:
+
+        homebank2ledger path/to/homebank.xhb -o ledger.dat \
+            --rename-account '^Liabilities:Chase VISA$=Liabilities:All Credit Cards' \
+            --rename-account '^Liabilities:Amex$=Liabilities:All Credit Cards'
+
+    If you need to do anything more complicated, of course you can edit the
+    output after converting; it's just plain text.
+
+ Beancount
+
+        # Convert homebank.xhb to a Beancount-compatible file:
+        homebank2ledger path/to/homebank.xhb -f beancount -o ledger.beancount
+    
+        # Run the balances report:
+        bean-report ledger.beancount balances
+
+CAVEATS
+
+      * I didn't intend to make this a releasable robust product, so it's
+      lacking tests.
+
+      * Budgets and scheduled transactions are not (yet) converted.
+
+      * There are some minor formatting tweaks I will make (e.g.
+      consolidate transaction tags and payees)

 
 BUGS
 
 
 BUGS