Version 0.002
authorCharles McGarvey <chazmcgarvey@brokenzipper.com>
Thu, 13 Jun 2019 05:39:54 +0000 (23:39 -0600)
committerCharles McGarvey <chazmcgarvey@brokenzipper.com>
Thu, 13 Jun 2019 05:39:54 +0000 (23:39 -0600)
13 files changed:
Changes
META.json
META.yml
Makefile.PL
README
bin/homebank2ledger
lib/App/HomeBank2Ledger.pm
lib/App/HomeBank2Ledger/Formatter.pm
lib/App/HomeBank2Ledger/Formatter/Beancount.pm
lib/App/HomeBank2Ledger/Formatter/Ledger.pm
lib/App/HomeBank2Ledger/Ledger.pm
lib/App/HomeBank2Ledger/Util.pm
lib/File/HomeBank.pm

diff --git a/Changes b/Changes
index decc1132c61c89033c63fd866e9102bc1ef53bf3..b46ff94d96b94b72b9ea2c05630c3df9aa73f9b2 100644 (file)
--- a/Changes
+++ b/Changes
@@ -1,4 +1,8 @@
-Revision history for homebank2ledger.
+Revision history for App-HomeBank2Ledger.
+
+0.002     2019-06-12 23:39:32-06:00 MST7MDT
+  * Rename dist
+  * Provide better README in dist
 
 0.001     2019-06-12 22:54:58-06:00 MST7MDT
   * Initial early development release
index a7a8999307a4b6ba9e5f6dca5c5c99f1e0220b4d..abb57bad690fb7deae4b00e88feff7e7d63e437d 100644 (file)
--- a/META.json
+++ b/META.json
@@ -12,7 +12,7 @@
       "url" : "http://search.cpan.org/perldoc?CPAN::Meta::Spec",
       "version" : 2
    },
-   "name" : "homebank2ledger",
+   "name" : "App-HomeBank2Ledger",
    "no_index" : {
       "directory" : [
          "eg",
    "provides" : {
       "App::HomeBank2Ledger" : {
          "file" : "lib/App/HomeBank2Ledger.pm",
-         "version" : "0.001"
+         "version" : "0.002"
       },
       "App::HomeBank2Ledger::Formatter" : {
          "file" : "lib/App/HomeBank2Ledger/Formatter.pm",
-         "version" : "0.001"
+         "version" : "0.002"
       },
       "App::HomeBank2Ledger::Formatter::Beancount" : {
          "file" : "lib/App/HomeBank2Ledger/Formatter/Beancount.pm",
-         "version" : "0.001"
+         "version" : "0.002"
       },
       "App::HomeBank2Ledger::Formatter::Ledger" : {
          "file" : "lib/App/HomeBank2Ledger/Formatter/Ledger.pm",
-         "version" : "0.001"
+         "version" : "0.002"
       },
       "App::HomeBank2Ledger::Ledger" : {
          "file" : "lib/App/HomeBank2Ledger/Ledger.pm",
-         "version" : "0.001"
+         "version" : "0.002"
       },
       "App::HomeBank2Ledger::Util" : {
          "file" : "lib/App/HomeBank2Ledger/Util.pm",
-         "version" : "0.001"
+         "version" : "0.002"
       },
       "File::HomeBank" : {
          "file" : "lib/File/HomeBank.pm",
-         "version" : "0.001"
+         "version" : "0.002"
       }
    },
    "release_status" : "stable",
          "web" : "https://github.com/chazmcgarvey/homebank2ledger"
       }
    },
-   "version" : "0.001",
+   "version" : "0.002",
    "x_authority" : "cpan:CCM",
    "x_generated_by_perl" : "v5.28.0",
    "x_serialization_backend" : "Cpanel::JSON::XS version 4.08"
index ca2694cf5a32a7d1a47f1b659de3a73dd86e7b1f..e66966af36a745a52554e37bc49bede42881cc94 100644 (file)
--- a/META.yml
+++ b/META.yml
@@ -17,7 +17,7 @@ license: mit
 meta-spec:
   url: http://module-build.sourceforge.net/META-spec-v1.4.html
   version: '1.4'
-name: homebank2ledger
+name: App-HomeBank2Ledger
 no_index:
   directory:
     - eg
@@ -28,25 +28,25 @@ no_index:
 provides:
   App::HomeBank2Ledger:
     file: lib/App/HomeBank2Ledger.pm
-    version: '0.001'
+    version: '0.002'
   App::HomeBank2Ledger::Formatter:
     file: lib/App/HomeBank2Ledger/Formatter.pm
-    version: '0.001'
+    version: '0.002'
   App::HomeBank2Ledger::Formatter::Beancount:
     file: lib/App/HomeBank2Ledger/Formatter/Beancount.pm
-    version: '0.001'
+    version: '0.002'
   App::HomeBank2Ledger::Formatter::Ledger:
     file: lib/App/HomeBank2Ledger/Formatter/Ledger.pm
-    version: '0.001'
+    version: '0.002'
   App::HomeBank2Ledger::Ledger:
     file: lib/App/HomeBank2Ledger/Ledger.pm
-    version: '0.001'
+    version: '0.002'
   App::HomeBank2Ledger::Util:
     file: lib/App/HomeBank2Ledger/Util.pm
-    version: '0.001'
+    version: '0.002'
   File::HomeBank:
     file: lib/File/HomeBank.pm
-    version: '0.001'
+    version: '0.002'
 requires:
   Carp: '0'
   Exporter: '0'
@@ -65,7 +65,7 @@ resources:
   bugtracker: https://github.com/chazmcgarvey/homebank2ledger/issues
   homepage: https://github.com/chazmcgarvey/homebank2ledger
   repository: https://github.com/chazmcgarvey/homebank2ledger.git
-version: '0.001'
+version: '0.002'
 x_authority: cpan:CCM
 x_generated_by_perl: v5.28.0
 x_serialization_backend: 'YAML::Tiny version 1.73'
index 407f870cb3aa241e3bea3a815fa21470a5cbf8e0..29683a7841cb201dca9c66ae37096833234284ae 100644 (file)
@@ -12,13 +12,13 @@ my %WriteMakefileArgs = (
   "CONFIGURE_REQUIRES" => {
     "ExtUtils::MakeMaker" => 0
   },
-  "DISTNAME" => "homebank2ledger",
+  "DISTNAME" => "App-HomeBank2Ledger",
   "EXE_FILES" => [
     "bin/homebank2ledger"
   ],
   "LICENSE" => "mit",
   "MIN_PERL_VERSION" => "5.006",
-  "NAME" => "homebank2ledger",
+  "NAME" => "App::HomeBank2Ledger",
   "PREREQ_PM" => {
     "Carp" => 0,
     "Exporter" => 0,
@@ -41,7 +41,7 @@ my %WriteMakefileArgs = (
     "IPC::Open3" => 0,
     "Test::More" => 0
   },
-  "VERSION" => "0.001",
+  "VERSION" => "0.002",
   "test" => {
     "TESTS" => "t/*.t"
   }
diff --git a/README b/README
index edf80f67b68867f093deecf76776401eb0fd5934..8bb567f67b4fd9c93edc38789f01d56850e331a5 100644 (file)
--- a/README
+++ b/README
 NAME
 
-    App::HomeBank2Ledger - A tool to convert HomeBank files to Ledger
-    format
+    homebank2ledger - A tool to convert HomeBank files to Ledger format
 
 VERSION
 
-    version 0.001
+    version 0.002
 
 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
 
-    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
 
index 2e398b5980c5bc944fdcd3eef22e806532e8d9c1..84ce034e163dde859924bb123997554af821144f 100644 (file)
@@ -8,7 +8,7 @@ use strict;
 
 use App::HomeBank2Ledger;
 
-our $VERSION = '0.001'; # VERSION
+our $VERSION = '0.002'; # VERSION
 
 App::HomeBank2Ledger->main(@ARGV);
 
@@ -24,13 +24,12 @@ homebank2ledger - A tool to convert HomeBank files to Ledger format
 
 =head1 VERSION
 
-version 0.001
+version 0.002
 
 =head1 SYNOPSIS
 
-    homebank2ledger --input FILEPATH [--output FILEPATH]
-                    [--version|--help|--manual]
-                    [--format FORMAT] [--account-width NUM]
+    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]
index 13cb9d2f57f4837a4ec9be41d4e224ca792039de..64cb0307483540b3b9d131a4b28ee8ab44c0f67d 100644 (file)
@@ -11,7 +11,7 @@ use File::HomeBank;
 use Getopt::Long 2.38 qw(GetOptionsFromArray);
 use Pod::Usage;
 
-our $VERSION = '0.001'; # VERSION
+our $VERSION = '0.002'; # VERSION
 
 my %ACCOUNT_TYPES = (   # map HomeBank account types to Ledger accounts
     bank        => 'Assets:Bank',
@@ -382,7 +382,7 @@ App::HomeBank2Ledger - A tool to convert HomeBank files to Ledger format
 
 =head1 VERSION
 
-version 0.001
+version 0.002
 
 =head1 SYNOPSIS
 
index 3113ecb8781a0e6f9e7375c78d2e303060da26cc..88895774a2cb45688b1bba0edf835f124398ab9f 100644 (file)
@@ -9,7 +9,7 @@ use Module::Load;
 use Module::Pluggable search_path   => [__PACKAGE__],
                       sub_name      => 'available_formatters';
 
-our $VERSION = '0.001'; # VERSION
+our $VERSION = '0.002'; # VERSION
 
 sub _croak { require Carp; Carp::croak(@_) }
 
@@ -59,7 +59,7 @@ App::HomeBank2Ledger::Formatter - Abstract class for formatting a ledger
 
 =head1 VERSION
 
-version 0.001
+version 0.002
 
 =head1 SYNOPSIS
 
index 515e5ec55d032dd0990cd6659c3587a5518d46a5..f6da01744ef7db0750af602046a2e14b0d48b524 100644 (file)
@@ -9,7 +9,7 @@ use App::HomeBank2Ledger::Util qw(commify rtrim);
 
 use parent 'App::HomeBank2Ledger::Formatter';
 
-our $VERSION = '0.001'; # VERSION
+our $VERSION = '0.002'; # VERSION
 
 my %STATUS_SYMBOLS = (
     cleared => '*',
@@ -257,7 +257,7 @@ App::HomeBank2Ledger::Formatter::Beancount - Beancount formatter
 
 =head1 VERSION
 
-version 0.001
+version 0.002
 
 =head1 DESCRIPTION
 
index 8fba2a3b6b22ae91b7db2d7a323daa1ba22b0756..e3181401a140b0e868c8f89ba64bb56541e7b82c 100644 (file)
@@ -9,7 +9,7 @@ use App::HomeBank2Ledger::Util qw(commify rtrim);
 
 use parent 'App::HomeBank2Ledger::Formatter';
 
-our $VERSION = '0.001'; # VERSION
+our $VERSION = '0.002'; # VERSION
 
 my %STATUS_SYMBOLS = (
     cleared => '*',
@@ -215,7 +215,7 @@ App::HomeBank2Ledger::Formatter::Ledger - Ledger formatter
 
 =head1 VERSION
 
-version 0.001
+version 0.002
 
 =head1 DESCRIPTION
 
index 18522cb55861a86f1557e4df76fb0ad181130626..258571ca49d6c62acb42618449df1ebb759995a8 100644 (file)
@@ -5,7 +5,7 @@ package App::HomeBank2Ledger::Ledger;
 use warnings;
 use strict;
 
-our $VERSION = '0.001'; # VERSION
+our $VERSION = '0.002'; # VERSION
 
 
 sub new {
@@ -63,7 +63,7 @@ App::HomeBank2Ledger::Ledger - Ledger data representation
 
 =head1 VERSION
 
-version 0.001
+version 0.002
 
 =head1 SYNOPSIS
 
@@ -86,59 +86,17 @@ Here is a specification for the substructures:
 This is a fully-qualified account name. Names may contain colons for representing a hierarchy of
 accounts. Examples:
 
-=head1 ATTRIBUTES
-
-=head2 accounts
-
-Get an arrayref of accounts.
-
-=head2 commodities
-
-Get an arrayref of commodities.
-
-=head2 payees
-
-Get an arrayref of payees.
-
-=head2 tags
-
-Get an arrayref of tags.
-
-=head2 transactions
-
-Get an arrayref of transactions.
-
-=head1 METHODS
-
-=head2 new
-
-    $ledger = App::HomeBank2Ledger::Ledger->new(%ledger_data);
-
-Construct a new ledger instance.
-
-=head2 add_accounts
-
-Add accounts.
-
-=head2 add_commodities
-
-Add commodities.
-
-=head2 add_payees
+=over 4
 
-Add payees.
-
-=head2 add_tags
+=item *
 
-Add tags.
+"Assets:Bank:Chase1234"
 
-=head2 add_transactions
+=item *
 
-Add transactions.
+"Liabilities:Credit Card:CapitalOne"
 
-=for: list
-* "Assets:Bank:Chase1234"
-* "Liabilities:Credit Card:CapitalOne"
+=back
 
 =head2 commodity
 
@@ -191,6 +149,56 @@ This is a hashref like this:
         ],
     }
 
+=head1 ATTRIBUTES
+
+=head2 accounts
+
+Get an arrayref of accounts.
+
+=head2 commodities
+
+Get an arrayref of commodities.
+
+=head2 payees
+
+Get an arrayref of payees.
+
+=head2 tags
+
+Get an arrayref of tags.
+
+=head2 transactions
+
+Get an arrayref of transactions.
+
+=head1 METHODS
+
+=head2 new
+
+    $ledger = App::HomeBank2Ledger::Ledger->new(%ledger_data);
+
+Construct a new ledger instance.
+
+=head2 add_accounts
+
+Add accounts.
+
+=head2 add_commodities
+
+Add commodities.
+
+=head2 add_payees
+
+Add payees.
+
+=head2 add_tags
+
+Add tags.
+
+=head2 add_transactions
+
+Add transactions.
+
 =head1 BUGS
 
 Please report any bugs or feature requests on the bugtracker website
index 58bc80f315c89ef0325d9b737e7cdd21c08e01ab..64c0cb2ab53fc5d1a5ac6ae2db5bb2aa6314f83c 100644 (file)
@@ -6,7 +6,7 @@ use strict;
 
 use Exporter qw(import);
 
-our $VERSION = '0.001'; # VERSION
+our $VERSION = '0.002'; # VERSION
 
 our @EXPORT_OK = qw(commify rtrim);
 
@@ -42,7 +42,7 @@ App::HomeBank2Ledger::Util - Miscellaneous utility functions
 
 =head1 VERSION
 
-version 0.001
+version 0.002
 
 =head1 FUNCTIONS
 
index 2c0a2d3627e61293d5ddd78192acfca9670b9e01..b5171103b3dab379315064d16b25c7b3da950951 100644 (file)
@@ -12,7 +12,7 @@ use Time::Piece;
 use XML::Entities;
 use XML::Parser::Lite;
 
-our $VERSION = '0.001'; # VERSION
+our $VERSION = '0.002'; # VERSION
 
 our @EXPORT_OK = qw(parse_string parse_file);
 
@@ -487,7 +487,7 @@ File::HomeBank - Parse HomeBank files
 
 =head1 VERSION
 
-version 0.001
+version 0.002
 
 =head1 SYNOPSIS
 
This page took 0.041671 seconds and 4 git commands to generate.