The hledger-interest package

[Tags: bsd3, program]

hledger-interest is a small command-line utility based on Simon Michael's hleder library. Its purpose is to compute interest for a given ledger account. Using command line flags, the program can be configured to use various schemes for day-counting, such as act/act, 30/360, 30E/360, and 30/360isda. Furthermore, it supports a (small) number of interest schemes, i.e. annual interest with a fixed rate and the scheme mandated by the German BGB288 (Basiszins für Verbrauchergeschäfte). Extending support for other schemes is fairly easy, but currently requires changes to the source code.

As an example, consider the following loan, stored in a file called test.ledger:

 2008/09/26 Loan
     Assets:Bank          EUR 10000.00
     Liabilities:Loan

 2008/11/27 Payment
     Assets:Bank          EUR -3771.12
     Liabilities:Loan

 2009/05/03 Payment
     Assets:Bank          EUR -1200.00
     Liabilities:Loan

 2010/12/10 Payment
     Assets:Bank          EUR -3700.00
     Liabilities:Loan

Suppose that loan earns 5% interest per year, and payments amortize interest before amortizing the principal claim, then the resulting ledger would look like this:

 $ hledger-interest --file=test.ledger --source=Expenses:Interest --target=Liabilities:Loan --30-360 --annual=0.05 Liabilities:Loan
 2008/09/26 Loan
     Assets:Bank              EUR  10000.00
     Liabilities:Loan

 2008/11/27 Payment
     Assets:Bank              EUR  -3771.12
     Liabilities:Loan

 2008/11/27 5.00% interest for EUR -10000.00 over 61 days
     Liabilities:Loan         EUR    -84.72
     Expenses:Interest

 2008/12/31 5.00% interest for EUR -6313.60 over 34 days
     Liabilities:Loan         EUR    -29.81
     Expenses:Interest

 2009/05/03 Payment
     Assets:Bank              EUR  -1200.00
     Liabilities:Loan

 2009/05/03 5.00% interest for EUR -6343.42 over 123 days
     Liabilities:Loan         EUR   -108.37
     Expenses:Interest

 2009/12/31 5.00% interest for EUR -5251.78 over 238 days
     Liabilities:Loan         EUR   -173.60
     Expenses:Interest

 2010/12/10 Payment
     Assets:Bank              EUR  -3700.00
     Liabilities:Loan

 2010/12/10 5.00% interest for EUR -5425.38 over 340 days
     Liabilities:Loan         EUR   -256.20
     Expenses:Interest

 2010/12/31 5.00% interest for EUR -1981.58 over 21 days
     Liabilities:Loan         EUR     -5.78
     Expenses:Interest

Running the utility with --help gives a brief overview over the available options:

 Usage: hledger-interest [OPTION...] ACCOUNT
   -h          --help            print this message and exit
   -V          --version         show version number and exit
   -v          --verbose         echo input ledger to stdout (default)
   -q          --quiet           don't echo input ledger to stdout
               --today           update account until today
   -f FILE     --file=FILE       input ledger file
   -s ACCOUNT  --source=ACCOUNT  interest source account
   -t ACCOUNT  --target=ACCOUNT  interest target account
               --act             use 'act' day counting convention
               --30-360          use '30/360' day counting convention
               --30E-360         use '30E/360' day counting convention
               --30E-360isda     use '30E/360isda' day counting convention
               --constant=RATE   constant interest rate
               --annual=RATE     annual interest rate
               --bgb288          compute interest according to German BGB288

[Skip to ReadMe]

Properties

Versions1.0, 1.1, 1.2, 1.3, 1.4, 1.4.1, 1.4.2, 1.4.3, 1.4.4
Change logNone available
Dependenciesbase (>=3 && <5), Cabal, hledger-lib (>=0.14), mtl, time [details]
LicenseBSD3
AuthorPeter Simons <simons@cryp.to>
MaintainerPeter Simons <simons@cryp.to>
CategoryFinance
Home pagehttp://github.com/peti/hledger-interest
Source repositoryhead: git clone git://github.com/peti/hledger-interest.git
Executableshledger-interest
UploadedFri Sep 2 18:09:52 UTC 2011 by PeterSimons
DistributionsDebian:1.4.4, NixOS:1.4.4
Downloads1287 total (83 in last 30 days)
Votes
0 []
StatusDocs not available [build log]
All reported builds failed as of 2015-05-31 [all 2 reports]

Downloads

Maintainers' corner

For package maintainers and hackage trustees

Readme for hledger-interest-1.3

hledger-interest

hledger-interest is a small command-line utility based on Simon Michael's hleder library. Its purpose is to compute interest for a given ledger account. Using command line flags, the program can be configured to use various day counting conventions, such as "act/act", "30/360", "30E/360", and "30/360isda". Furthermore, it supports several of different interest schemes, i.e. annual interest with a fixed rate and the scheme mandated by the German law § 288 BGB Verzugszinsen. Extending support for other schemes is fairly easy, but currently requires hacking the source code.

An overview over the available run-time options can be displayed by running "hleder-interest --help":

Usage: hledger-interest [OPTION...] ACCOUNT
  -v          --verbose         echo input ledger to stdout (default)
  -q          --quiet           don't echo input ledger to stdout
              --today           compute interest up until today
  -f FILE     --file=FILE       input ledger file (pass '-' for stdin)
  -s ACCOUNT  --source=ACCOUNT  interest source account
  -t ACCOUNT  --target=ACCOUNT  interest target account
              --act             use 'act' day counting convention
              --30-360          use '30/360' day counting convention
              --30E-360         use '30E/360' day counting convention
              --30E-360isda     use '30E/360isda' day counting convention
              --constant=RATE   constant interest rate
              --annual=RATE     annual interest rate
              --bgb288          compute interest according to German BGB288

When run, hledger-interest reads the ledger file designated by the --file flag and filters all transactions that change the account specified on the command line. All other accounts will be ignored. Every time a transaction modifies the given account's balance -- thereby changing the amount of money that earns interest --, hledger-interest transfers the interest that accrued so far. Interest will be debited from the account designed by the --source flag and credited to the account designed by the --target flag.

Examples

Suppose that you've loaned 1000 Euro from your bank at an annual interest rate of 5%, and that you would like to see how interest develops over time. Then you would create a ledger file, say loan.ledger, that looks something like this:

2010/09/26 Loan
    Assets:Bank                     EUR 1000.00
    Liabilities:Loan

Now, ledger-interest is run to determine the interest up until today:

$ hledger-interest -f loan.ledger --act --annual=0.05 --today -s Expenses:Interest -t Liabilities:Loan:Interest Liabilities:Loan
2010/09/26 Loan
    Assets:Bank                     EUR 1000.00
    Liabilities:Loan

2010/12/31 5.00% interest for EUR -1000.00 over 96 days
    Liabilities:Loan:Interest       EUR -13.15
    Expenses:Interest

2011/08/22 5.00% interest for EUR -1000.00 over 234 days
    Liabilities:Loan:Interest       EUR -32.05
    Expenses:Interest

Note a separate credit account for the interest was chosen: Liabilities:Loan:Interest. Consequently, interest accrued in one interest period does not earn interest in the following periods. If interest is credited to the main account instead, that behavior changes:

$ hledger-interest -f loan.ledger --act --annual=0.05 --today -s Expenses:Interest -t Liabilities:Loan Liabilities:Loan
2010/09/26 Loan
    Assets:Bank                     EUR 1000.00
    Liabilities:Loan

2010/12/31 5.00% interest for EUR -1000.00 over 96 days
    Liabilities:Loan                EUR -13.15
    Expenses:Interest

2011/08/22 5.00% interest for EUR -1013.15 over 234 days
    Liabilities:Loan                EUR -32.48
    Expenses:Interest

Of course, loans are supposed to be paid back, and these payments change the amount of interest accrued. Suppose that load.ledger would be extended by the following transactions:

2010/12/11 Payment
    Assets:Bank                     EUR -150.00
    Liabilities:Loan

2011/03/07 Payment
    Assets:Bank                     EUR -300.00
    Liabilities:Loan

2011/08/21 Payment
    Assets:Bank                     EUR -150.00
    Liabilities:Loan

Then interest would develop as follows:

$ hledger-interest -f loan.ledger --act --annual=0.05 -s Expenses:Interest -t Liabilities:Loan Liabilities:Loan
2010/09/26 Loan
    Assets:Bank                     EUR 1000.00
    Liabilities:Loan

2010/12/11 5.00% interest for EUR -1000.00 over 76 days
    Liabilities:Loan                EUR -10.41
    Expenses:Interest

2010/12/11 Payment
    Assets:Bank                     EUR -150.00
    Liabilities:Loan

2010/12/31 5.00% interest for EUR -860.41 over 20 days
    Liabilities:Loan                EUR -2.36
    Expenses:Interest

2011/03/07 5.00% interest for EUR -862.77 over 66 days
    Liabilities:Loan                EUR -7.80
    Expenses:Interest

2011/03/07 Payment
    Assets:Bank                     EUR -300.00
    Liabilities:Loan

2011/08/21 5.00% interest for EUR -570.57 over 167 days
    Liabilities:Loan                EUR -13.05
    Expenses:Interest

2011/08/21 Payment
    Assets:Bank                     EUR -150.00
    Liabilities:Loan

Last but not least, there is a special case known as "Verzugszinsen" in German law, which applies when someone is supposed to pay a bill, but fails to do so on time. For every day past the deadline, interest accrues according to terms specified in § 247 BGB. The command line flag --bgb288 enables this scheme in hledger-interest.

Let's assume that customer ACME is supposed to pay 35 Euro by 2010/09/15, but the money actually arrives almost half a year late:

2010/09/15 Services rendered to Customer ACME
    ACME                            EUR -35.00  ; 1 hour @ EUR 35.00
    Receivable:ACME

2011/03/17 ACME
    ACME                            EUR 35.00
    Receivable:ACME

According to German law, you are entitled to the following interest:

$ hledger-interest -f acme.ledger --quiet --bgb288 -s Income:Interest -t Receivable:ACME:Interest Receivable:ACME
2010/12/31 5.12% interest for EUR 35.00 over 107 days
    Receivable:ACME:Interest        EUR 0.53
    Income:Interest

2011/03/17 5.12% interest for EUR 35.00 over 76 days
    Receivable:ACME:Interest        EUR 0.37
    Income:Interest

So, if you're smart, then you'll book the payment so that the accrued interest is paid first:

2011/03/17 ACME
    ACME                            EUR 35.00
    Receivable:ACME:Interest        EUR -0.90
    Receivable:ACME

This gives the following transaction history for the ACME account:

$ hledger-interest -f acme.ledger --bgb288 -s Income:Interest -t Receivable:ACME:Interest Receivable:ACME |
  hledger -f - reg Receivable:ACME
2010/09/15 Services rendered .. Receivable:ACME           EUR 35.00    EUR 35.00
2010/12/31 5.12% interest for.. Re:ACME:Interest           EUR 0.53    EUR 35.53
2011/03/17 5.12% interest for.. Re:ACME:Interest           EUR 0.37    EUR 35.90
2011/03/17 ACME                 Re:ACME:Interest          EUR -0.90    EUR 35.00
                                Receivable:ACME          EUR -34.10     EUR 0.90