From 185d2cc01e85fc41bd14b06a0b1290c2e25a874a Mon Sep 17 00:00:00 2001 From: Charles McGarvey Date: Wed, 12 Jun 2019 23:39:54 -0600 Subject: [PATCH] Version 0.002 --- Changes | 6 +- META.json | 18 +- META.yml | 18 +- Makefile.PL | 6 +- README | 233 ++++++++++++++++-- bin/homebank2ledger | 9 +- lib/App/HomeBank2Ledger.pm | 4 +- lib/App/HomeBank2Ledger/Formatter.pm | 4 +- .../HomeBank2Ledger/Formatter/Beancount.pm | 4 +- lib/App/HomeBank2Ledger/Formatter/Ledger.pm | 4 +- lib/App/HomeBank2Ledger/Ledger.pm | 108 ++++---- lib/App/HomeBank2Ledger/Util.pm | 4 +- lib/File/HomeBank.pm | 4 +- 13 files changed, 311 insertions(+), 111 deletions(-) diff --git a/Changes b/Changes index decc113..b46ff94 100644 --- 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 diff --git a/META.json b/META.json index a7a8999..abb57ba 100644 --- 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", @@ -84,31 +84,31 @@ "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", @@ -123,7 +123,7 @@ "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" diff --git a/META.yml b/META.yml index ca2694c..e66966a 100644 --- 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' diff --git a/Makefile.PL b/Makefile.PL index 407f870..29683a7 100644 --- a/Makefile.PL +++ b/Makefile.PL @@ -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 edf80f6..8bb567f 100644 --- a/README +++ b/README @@ -1,52 +1,241 @@ 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 files to a + format usable by Ledger . It can also + convert directly to the similar 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 diff --git a/bin/homebank2ledger b/bin/homebank2ledger index 2e398b5..84ce034 100644 --- a/bin/homebank2ledger +++ b/bin/homebank2ledger @@ -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] diff --git a/lib/App/HomeBank2Ledger.pm b/lib/App/HomeBank2Ledger.pm index 13cb9d2..64cb030 100644 --- a/lib/App/HomeBank2Ledger.pm +++ b/lib/App/HomeBank2Ledger.pm @@ -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 diff --git a/lib/App/HomeBank2Ledger/Formatter.pm b/lib/App/HomeBank2Ledger/Formatter.pm index 3113ecb..8889577 100644 --- a/lib/App/HomeBank2Ledger/Formatter.pm +++ b/lib/App/HomeBank2Ledger/Formatter.pm @@ -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 diff --git a/lib/App/HomeBank2Ledger/Formatter/Beancount.pm b/lib/App/HomeBank2Ledger/Formatter/Beancount.pm index 515e5ec..f6da017 100644 --- a/lib/App/HomeBank2Ledger/Formatter/Beancount.pm +++ b/lib/App/HomeBank2Ledger/Formatter/Beancount.pm @@ -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 diff --git a/lib/App/HomeBank2Ledger/Formatter/Ledger.pm b/lib/App/HomeBank2Ledger/Formatter/Ledger.pm index 8fba2a3..e318140 100644 --- a/lib/App/HomeBank2Ledger/Formatter/Ledger.pm +++ b/lib/App/HomeBank2Ledger/Formatter/Ledger.pm @@ -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 diff --git a/lib/App/HomeBank2Ledger/Ledger.pm b/lib/App/HomeBank2Ledger/Ledger.pm index 18522cb..258571c 100644 --- a/lib/App/HomeBank2Ledger/Ledger.pm +++ b/lib/App/HomeBank2Ledger/Ledger.pm @@ -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 diff --git a/lib/App/HomeBank2Ledger/Util.pm b/lib/App/HomeBank2Ledger/Util.pm index 58bc80f..64c0cb2 100644 --- a/lib/App/HomeBank2Ledger/Util.pm +++ b/lib/App/HomeBank2Ledger/Util.pm @@ -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 diff --git a/lib/File/HomeBank.pm b/lib/File/HomeBank.pm index 2c0a2d3..b517110 100644 --- a/lib/File/HomeBank.pm +++ b/lib/File/HomeBank.pm @@ -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 -- 2.45.2