# hledger-interest

computes interest for a given account http://github.com/peti/hledger-interest

Version on this page:| 1.5.1  
---|---  
LTS Haskell 8.6:| 1.5.1  
Stackage Nightly 2017-02-11:| 1.5.1  
Latest on Hackage:| 1.5.1  
  
# 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
                  --bgb288          compute interest according to German BGB288

When run, hledger-interest reads the ledger file designated by the  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  flag and credited to the account designed by the  flag.`--file``--source``--target`

## 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 , that looks something like this:`loan.ledger`
    
    
    2010/09/26 Loan
        Assets:Bank                     EUR 1000.00
        Liabilities:Loan

Now,  is run to determine the interest up until today:`ledger-interest`
    
    
    $ 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: . 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:`Liabilities:Loan:Interest`
    
    
    $ 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  would be extended by the following transactions:`load.ledger`
    
    
    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  enables this scheme in .`--bgb288``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