org-contrib/babel/examples/ledger.org

   1 #+TITLE:     Using ledger for accounting in org with babel
   2 #+AUTHOR:    Eric S Fraga
   3 #+EMAIL:     e.fraga@ucl.ac.uk
   4 #+DATE:      2010.08.25 20:41:52
   5 #+DESCRIPTION:
   6 #+KEYWORDS:
   7 #+LANGUAGE:  en
   8 #+OPTIONS:   H:3 num:t toc:t \n:nil @:t ::t |:t ^:t -:t f:t *:t <:t
   9 #+OPTIONS:   TeX:t LaTeX:t skip:nil d:nil todo:t pri:nil tags:not-in-toc
  10 #+INFOJS_OPT: view:nil toc:nil ltoc:t mouse:underline buttons:0 path:http://orgmode.org/org-info.js
  11 #+EXPORT_SELECT_TAGS: export
  12 #+EXPORT_EXCLUDE_TAGS: noexport
  13 #+LINK_UP:
  14 #+LINK_HOME:
  15 #+XSLT:
  16
  17 #+STARTUP: oddonly
  18
  19 * Introduction
  20
  21 /Ledger/ is a double entry accounting system which uses simple text
  22 files for recording all transactions.  As such, it is fundamentally
  23 compatible with org mode in Emacs.  Using org-babel, it is possible
  24 to record financial transactions conveniently in an org file and
  25 subsequently generate the financial reports required.
  26
  27 *** Getting started
  28     :PROPERTIES:
  29     :ID:       a14c087b-c675-4b6f-b7d4-5974a140acb3
  30     :END:
  31
  32 With a recent version of org (7.01+), ledger support is provided.  To
  33 use it, enable ledger support.  Check the [[http://orgmode.org/worg/org-contrib/babel/index.php][org-babel documentation on
  34 Worg]] for instructions on how to achieve this but I currently do this
  35 directly as follows:
  36
  37 #+srcname: babel-language-setup
  38 #+begin_src emacs-lisp
  39 (org-babel-do-load-languages
  40  'org-babel-load-languages
  41  '((R . t)
  42    (ditaa . t)
  43    (dot . t)
  44    (emacs-lisp . t)
  45    (gnuplot . t)
  46    (haskell . nil)
  47    (latex . t)
  48    (ledger . t)         ;this is the important one for this tutorial
  49    (ocaml . nil)
  50    (octave . t)
  51    (python . t)
  52    (ruby . t)
  53    (screen . nil)
  54    (sh . t)
  55    (sql . nil)
  56    (sqlite . t)))
  57 #+end_src
  58
  59 Once ledger support in org-babel has been enabled, we can use the
  60 tangling support in org-babel to introduce ledger entries throughout
  61 an org file.
  62
  63 The rest of this document presents an example of how to do this but
  64 only scratches the surface of what is possible in /ledger/.  For further
  65 information on /ledger/, check out [[http://wiki.github.com/jwiegley/ledger/][the project website]].
  66
  67 * Embedded ledger example
  68
  69 In this example, we will separate the recording of financial
  70 transactions from the reporting of financial summaries.  The first
  71 subsection will present some simple expenses and income entries; the
  72 second subsection will show some example financial summaries you may
  73 wish to generate.
  74
  75 *** Income and expenses records
  76     :PROPERTIES:
  77     :tangle:   /tmp/account.ledger
  78     :END:
  79
  80     The property for this heading specifies where the tangled output
  81     of the ledger code blocks in what follows should end up.  I have
  82     specified the file =/tmp/account.ledger=. By default, the file will
  83     appear in the same directory where the org file resides but ledger
  84     will be invoked in =/tmp=, at least on a linux system so specifying
  85     the =/tmp= directory makes life easier.  However, please be aware of
  86     confidentiality problems with this approach!
  87
  88 ***** Income entries
  89       :PROPERTIES:
  90       :ID:       74fd73c2-41f9-41eb-97dd-1f8cb515d837
  91       :END:
  92
  93       The first set of entries relates to income, either monthly pay or
  94       interest, all typically going into one of my bank account.  Here
  95       I have placed several entries but we could have had each entry
  96       in a separate =src= block.
  97
  98 #+begin_src ledger
  99 2010/01/01 * Starting balance
 100   assets:bank:savings  £1300.00
 101   income:starting balances
 102 2010/07/22 * Got paid
 103   assets:bank:chequing  £1000.00
 104   income:salary
 105 2010/07/31 * Interest on bank savings
 106   assets:bank:savings  £3.53
 107   income:interest
 108 2010/07/31 * Transfer savings
 109   assets:bank:savings  £250.00
 110   assets:bank:chequing
 111 2010/08/01 got paid again
 112   assets:bank:chequing  £1000.00
 113   income:salary
 114 #+end_src
 115
 116 ***** expenses
 117       :PROPERTIES:
 118       :ID:       07d84b1d-892b-4367-86da-95a0380b8a45
 119       :END:
 120
 121       The following entries relate to personal expenses, such as rent
 122       and food.  Again, these have all been placed in a single =src=
 123       block but could have been done individually.
 124
 125 #+begin_src ledger
 126 2010/07/23 Rent
 127   expenses:rent  £500.00
 128   assets:bank:chequing
 129 2010/07/24 Food
 130   expenses:food  £150.00
 131   assets:bank:chequing
 132 #+end_src
 133
 134 *** Financial summaries
 135
 136     Assuming you have tangled the ledger entries (=C-c C-v t=), you can now
 137     perform all kinds of calculations.  However, please *note* that
 138     despite tangling to the current directory (where this org file
 139     resides), on Linux systems at least, the direct execution of babel
 140     =src= blocks takes place in =/tmp= so any references to the tangled
 141     file generated must have the full path.
 142
 143 ***** An overall balance summary
 144       :PROPERTIES:
 145       :ID:       b9747939-6380-495d-9520-aad8e4bf80ad
 146       :END:
 147
 148       The overall balance of your account and expenditure with a breakdown
 149       according to category is specified by passing the =bal= argument
 150       to /ledger/.
 151
 152 #+begin_src ledger :cmdline bal :results value
 153 !include /tmp/account.ledger
 154 #+end_src
 155
 156 #+results:
 157 :            £2653.53  assets
 158 :             £650.00  expenses
 159 :           £-3303.53  income
 160
 161 If you want a more detailed breakdown of where your money is and where
 162 it has been spent, you can specify the =-s= flag to tell /ledger/ to
 163 include sub-accounts in the report.
 164
 165 #+begin_src ledger :cmdline -s bal :results value
 166 !include /tmp/account.ledger
 167 #+end_src
 168
 169 #+results:
 170 #+begin_example
 171            £2653.53  assets:bank
 172            £1100.00    chequing
 173            £1553.53    savings
 174             £650.00  expenses
 175             £150.00    food
 176             £500.00    rent
 177           £-3303.53  income
 178              £-3.53    interest
 179           £-2000.00    salary
 180           £-1300.00    starting balances
 181 #+end_example
 182
 183
 184 ***** Generating a monthly register
 185       :PROPERTIES:
 186       :ID:       d9a89c50-33fd-42cc-a6ed-adcf263422d8
 187       :END:
 188
 189       You can also generate a monthly register by executing the
 190       following =src= block.  This presents a summary of transactions
 191       for each monthly period with a running total in the final column
 192       (which should be 0 at the end if all the entries are correct).
 193
 194 #+begin_src ledger :cmdline -M reg
 195 !include /tmp/account.ledger
 196 #+end_src
 197
 198 #+results:
 199 #+begin_example
 200 2010/01/01 - 2010/01/31         assets:bank:savings       £1300.00    £1300.00
 201                                 in:starting balances     £-1300.00            0
 202 2010/07/01 - 2010/07/31         assets:bank:chequing       £100.00     £100.00
 203                                 assets:bank:savings        £253.53     £353.53
 204                                 expenses:food              £150.00     £503.53
 205                                 expenses:rent              £500.00    £1003.53
 206                                 income:interest             £-3.53    £1000.00
 207                                 income:salary            £-1000.00            0
 208 2010/08/01 - 2010/08/01         assets:bank:chequing      £1000.00    £1000.00
 209                                 income:salary            £-1000.00            0
 210 #+end_example
 211
 212 We could also generate a monthly report on our =assets= showing how
 213 these are increasing (or decreasing!).  In this case, the final column
 214 will be the running total of the =assets= in our ledger.
 215
 216 #+begin_src ledger :cmdline -M reg assets
 217 !include /tmp/account.ledger
 218 #+end_src
 219
 220 #+results:
 221 : 2010/01/01 - 2010/01/31         assets:bank:savings       £1300.00    £1300.00
 222 : 2010/07/01 - 2010/07/31         assets:bank:chequing       £100.00    £1400.00
 223 :                                 assets:bank:savings        £253.53    £1653.53
 224 : 2010/08/01 - 2010/08/01         assets:bank:chequing      £1000.00    £2653.53
 225
 226 * Summary
 227
 228 This short tutorial shows how /ledger/ entries can be embedded in a org
 229 file and manipulated using [[http://orgmode.org/worg/org-contrib/babel/index.php][org-babel]].  However, only simple /ledger/
 230 features have been illustrated; please refer to the /ledger/
 231 [[http://wiki.github.com/jwiegley/ledger/][documentation]] for examples of more complex interations with a ledger.