Hackage :: [Package]

hledger-interest: computes interest for a given account

[ bsd3, finance, program ] [ Propose Tags ] [ Report a vulnerability ]

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 fuer Verbrauchergeschaefte). 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:Bank

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

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

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

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:Bank --30-360 --annual=0.05 Liabilities:Bank
2008/09/26 Loan
    Assets:Bank              EUR  10000.00
    Liabilities:Bank

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

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

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

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

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

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

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

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

2010/12/31 5.00% interest for EUR -1981.58 over 21 days
    Liabilities:Bank         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                     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
  -I          --ignore-assertions         ignore any failing balance assertions
              --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-schedule=SCHEDULE  schedule of annual interest rates.
                                          syntax: '[(Date1,Rate1),(Date2,Rate2),...]'
              --annual=RATE               annual interest rate
              --bgb288                    compute interest according to German BGB288
[Skip to Readme]

Downloads

Note: This package has metadata revisions in the cabal description newer than included in the tarball. To unpack the package including the revisions, use 'cabal get'.

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees

Candidates

  • No Candidates
Versions [RSS] 1.0, 1.1, 1.2, 1.3, 1.4, 1.4.1, 1.4.2, 1.4.3, 1.4.4, 1.5, 1.5.1, 1.5.2, 1.5.3, 1.5.4, 1.5.5, 1.6.0, 1.6.1, 1.6.2, 1.6.3, 1.6.4, 1.6.5, 1.6.6
Dependencies base (>=3 && <5), Cabal, Decimal, hledger-lib (>=1.26 && <1.41), mtl, text, time [details]
Tested with ghc ==8.4.4, ghc ==8.6.5, ghc ==8.8.4, ghc ==8.10.7, ghc ==9.0.2, ghc ==9.2.8, ghc ==9.4.7, ghc ==9.6.1
License BSD-3-Clause
Author Peter Simons <simons@cryp.to>
Maintainer Peter Simons <simons@cryp.to>
Revised Revision 5 made by PeterSimons at 2024-10-26T13:10:24Z
Category Finance
Home page https://github.com/peti/hledger-interest
Source repo head: git clone https://github.com/peti/hledger-interest.git
Uploaded by PeterSimons at 2023-09-04T17:57:37Z
Distributions Debian:1.6.0, LTSHaskell:1.6.6, NixOS:1.6.6, Stackage:1.6.6, openSUSE:1.6.6
Reverse Dependencies 1 direct, 0 indirect [details]
Executables hledger-interest
Downloads 13750 total (86 in the last 30 days)
Rating (no votes yet) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs not available [build log]
Last success reported on 2023-09-04 [all 1 reports]

Readme for hledger-interest-1.6.6

[back to package description]

hledger-interest

hledger-interest is a small command-line utility based on Simon Michael's hlegder 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
              --annual-schedule=SCHEDULE  schedule of annual interest rates.
                                          syntax: '[(Date1,Rate1),(Date2,Rate2),...]'
              --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                            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