Issue 20

by Alaric Snell-Pym

2011-03-24 +0000

0. Introduction

Welcome to the 20th issue of the Chicken Gazette. While the gazette was on hiatus the chicken community was definitely not. We are expecting a new release and lots of bugs have been addressed in the meantime.

Thanks for the recipe go to Alaric. Thanks to the Chicken Team for compiling this issue.

Enjoy!

1. Hatching Farm

The following new extensions were added:

The following new versions have been released:

2. Chicken Talk

Chicken 4.7 is about to be released. The development team is performing some final tests to check if some critical bug shows up before the release. If you want to help testing the code which is going to be the next Chicken version, get the latest development snapshot and give it a try.

A Chicken-based commercial application has been added to the Software wiki page. According to the description, AuScio ''is simple cross-platform metal price monitor combining the qt-light, tcp and srfi-18 multi-threading eggs. The application is deployed as a native executable with Chicken's compiler''.

On the hobbyist side Lispy, a scheme interpreter written in Chicken by jacktrades has been found on the net.

Evan Hanson reported a Chicken sighting in the Computer Music Journal's DVD.

Thanks go also to John Cowan who brought the Chicken Dance License as a possible new license to our attention :)

Matt Welland announced a new version of chicken-iup here. Also note that the download link has changed since the last Gazette.

YC started a discussion about a Generic RDBMS Interface, where lots of people envisioned an easy to use glue to access RDBMS. The participants argued over the use of URL encoded queries vs. other more lispy forms. Thomas Chust developed a prototype and is looking for feedback. Thanks!

John Magolske shows us a nice trick to use csi within Vim to evaluate visually selected text. He also ran into issues when installing chicken eggs in a nonstandard location w/o hard coding in these paths during compilation. Thanks to the helpful people on chicken-users he could solve his issue.

Matt Welland asks for a way to produce a notification sound in a cross platform way in this mail but until now we don't have a good answer for this yet. Maybe you can help? Matt is also still waiting for an answer to a problem with srfi-19 under windows.

Felix announced the release of the hopefully latest development snapshot before the next major release. Please test 4.6.7 as hard as you can.

Chris Bolton asked about how to print colored messages to a terminal and learned about the fmt egg and ansi escape sequences.

John J Foerch asked for a spiffy feature: remote-address should also take the X-Forwarded-For header into account when generating an address. Peter Bex kindly implemented it.

Alex Shinn announced the R7RS draft which we all waited for. Thanks to the scheme-report group!

Steve Graham asked about the possibility of writing android apps in chicken. Moritz Heidkamp promised to write a gazette recipe about it "in the near future".

William Xu asked about a way to upgrade all installed eggs. Felix added a '-reinstall' option to chicken-install which you are invited to test.

Thanks to Alan Post, Mario Goulart has been able to fix the links to the tests.call-cc.org egg feeds.

3. Omelette Recipes

The dream of many Schemers is to write Scheme for a living. Due to the regrettable tendency of employers to frown upon good ideas, the best way to achieve this is to start your own company, so you can be your own boss, and frown upon the good ideas of others instead.

However, running your own company comes at a price; and a big part of that price is the horror of "book keeping"; the requirement to track all flows of money and other, more abstract, forms of value in and out of your company.

Some people will tell you book-keeping is simple. "Just keep all your receipts and bank statements and bills and invoices", they say. "Then send them to your accountant at the end of the year."

"But what about value-added tax?", you ask (or "sales tax" in some countries). "And what about income tax paid at source for my employees (including myself)?". "And why do I need to pay an accountant so much to do a job that a computer can easily do in milliseconds?" And then the smug smile slowly drips from the face of the "Oh it's easy" crowd.

Clearly, book-keeping is complicated. And yet also simple, in that it is determined by sets of rules.

We know what to do, don't we? Let's get coding!

The problem is that book-keeping involves several different kinds of inputs - bills (that people send you), invoices (that you send people), transfers of money (bills and invoices being paid), loans (to and from the company), employees being paid, interest payments from the bank, dividend payments, and so on; while it also involves several different outputs - tax reports for the various taxes involved (in the UK, I had to deal with VAT every three months, income tax and national insurance when paying myself and my wife as employees every month, an annual filing fee, and annual corporation tax and dividend payments), statutory filing of certain financial summaries (generally annually), and internal reporting: How much was I spending? How much did each client owe? How much should be in the bank by when? Plus, it's nice to be able to generate nice invoices to send to folks who owe you money. That's a form of specialised report, too, just reporting on a single invoice.

Each of the output reports depend in complex ways on different information from the inputs. The VAT reports mainly have to add up how much VAT I've paid when being billed by others, and how much VAT I've charged when invoicing - meaning that VAT needs to be tracked on all bills and invoices so it can be extracted. They also want to know totals of actual money in and out of the company in the period (even stuff where VAT isn't an issue), presumably to check up on me. Meanwhile, end of year reports tend to need to know how much I've invoiced for various different kinds of work, and what I've spent on what kinds of things: buying equipment that will last me for several years is handled differently to expenses like travel, or buying stuff that I eventually resell to clients (so in our invoices, we need to keep track of money charged for services separately to money charged for things).

Some reports care about virtual money moving hands. As soon as I invoice somebody, then the company now has a virtual asset - some money owed to it. That's worth as much as cash in the bank from some perspectives (generally, I have to pay tax on it as soon as it's invoiced, even if I've not been paid). And yet some care only about actual cash changing hands (working out my bank balance, for instance).

Sometimes our clients invite us to incur expenses in doing work for them (such as extra travel) and then invoice them on for those expenses, so they pay us back - in which case, expenses need to be able to be tied to invoices, as well. Sometimes we decide to cancel an invoice, which can't be done by just pretending it never existed, for audit-trail reasons; we need to issue a "negative" invoice called a credit note.

Just to complicate matters more, the actual movement of money isn't atomic. If I invoice somebody on date A, they might post me a cheque which arrives on date B, which I pay into the bank on date C, which actually clears into the account (and thereby appears on my bank statement, when I get it) on date D. So at date A the company now has a "we are owed" pretend-money asset, which goes through various stages until it finally turns into money in the bank on date D.

I handled my book-keeping with some hacky scripts written in Chicken Scheme. What I'm going to document here is partly what I've done, and partly what I should have done - it was a very iterative process, refining the best way to handle stuff, and there's lots of improvements I've wanted to make but not had time to. So I'm going to describe the ideal case, not the hacky half-way house I actually have right now!

The approach I took was to have a file called a "ledger" that I enter all my invoices and so on into. This is parsed to build up a bunch of data structures in memory, from which the various reports can easily be obtained. Firstly, for each kind of input object (invoices, bills, etc) there's a list of them, or more often a hashmap to make them easy to find by some identifier (I can give my invoices unique symbolic names, for instance). That contains the raw data as parsed from the ledger file. But then we also create summary structures, which are used by the more general reports to generate their output without having to special-case each and every different input object type, and to enable sharing of common functionality between reports.

The main summary structure is the double-entry transaction list, which models the entire financial activity of the company as transfers between accounts.

Imagine I invoice Widget Corp for setting up and installing a router:

 INVOICE INV005: Issued 2011-04-25
 Router setup and installation: GBP 800
 1 router from my stock: GBP 350
 1 train ticket for me to go to their site: GBP 35 (no VAT due)
 Subtotal: GBP 1,185
 VAT on the above: GBP 230
 Total due: GBP 1,415

As part of the work, I lose a router (worth GBP 350) from my stock, and have to spend GBP 35 on a train fare.

This might expand into the following transactions:

* 2011-03-02: "Expense for Widget Corp (INV005)"
  * expenses.travel +35 "Travel to site"
  * cash -35
* 2011-04-25 "Invoice Widget Corp (INV005)"
  * income.work -800 (Router set up and installation)
  * stock.balances -350 (1 of LX300 router, serial number 0343248)
  * clients.widgetcorp.expenses -35 (Travel 2011-03-02)
  * taxes.vat -230
  * clients.widgetcorp.balance +1415

And, eventually, they might pay me, which hits my bank account some time later:

* 2011-05-07 "Payment from Widget Corp (INV005)"
  * clients.widgetcorp.balance -1415
  * bank.balance +1415

And then one day I'll pay my VAT bill, which will look something like:

* 2011-06-01 "VAT payment for period from 2011-03-01 to 2011-06-01"
  * taxes.vat 230
  * bank.balance -230

Note a few tricky things. Each transaction's "splits", as the lines within them are known, have to sum to zero for everything to balance correctly, which tells us that nothing has gone missing. So when we start being owed GBP 1,415 by Widget Corp, we need to account for where that asset has come from. Special accounts with names such as "income.work" (for value generated by me working) and "clients.widgetcorp.expenses" (for previously-paid expenses that, as of this invoice, I can charge the client for) pop into existence. "taxes.vat" looks as if VAT is a form of income for me, as money comes "from" it in the transaction - which is sort of true; I'm charging Widget Corp for some VAT alongside for the actual work done. Figuring out what signs to put on all the items in the invoice is mind-bending and painful, but if you just concentrate on making it all add up to zero in the end and starting from things that are obvious (is money going into or out of the bank account, or the "owed to me by this customer" account?), you can figure it out.

From the above, we can start to flesh out some data structures:

(define-record txn
	       date customer code description splits)

(define-record txn-split
	       account amount notes)


(define *txns* (make-hash-table))
(define (register-txn! txn)
  (if (hash-table-exists? *txns* (txn-date txn))
      (begin
	(set! (hash-table-ref *txns* (txn-date txn))
	      (cons txn
		    (hash-table-ref *txns* (txn-date txn)))))
      (begin
	(set! (hash-table-ref *txns* (txn-date txn))
	      (list txn)))))

What is an "account"? There's a few kinds, and what kind of account it is matters in reporting. Accounts might be assets within the company - such as "clients.widgetcorp.balance" or "bank.balance" or "stock.balance". Or they may be places where money (be it real or virtual) is created from or destroyed by (from the perspective of the company), such as "income.work" and "expenses.travel". The important difference is that balance-type accounts have a balance that is increased when money is sent to them and decreased when it's taken out, and that balance is part of the value of the company, while the income/expense type accounts don't. In my terminology, these are "balance" accounts and "delta" accounts. Each account also begins to a group, used to aggregate them in reports: there's income accounts, bank accounts, client accounts, and so on. And accounts may be tied to a third party - I've given an example of a client above, but also, the organisations that send me bills have balances (the money I owe them). In general, every third party (be they ones that bill me, or ones that I invoice, or both - I've interacted with other freelancers, sometimes working for them, sometimes vice versa) has a set of accounts attached to them for their balance, expenses I can claim from them, and so on. That implies another set of record types:

(define-record third-party
	       name address balance-account expenses-account)

(define-record account
	       name type group third-party)


(define *third-parties* (make-hash-table))
(define *accounts* (make-hash-table))

(define (find-account acct-name)
  (hash-table-ref *accounts* acct-name))

(define (register-account! acct)
  (set! (hash-table-ref *accounts* (account-name acct)) acct))

An account's third-party slot may be #f if it's not part of a third party.

Accounts are the organisational structure that turns a sea of financial events into something we can start to make sense of. In the next thrilling installment, we will look at actually entering transactions, and turning them into a data structure from which useful reports can be produced...

4. About the Chicken Gazette

The Gazette is produced occasionally by a volunteer from the Chicken community. The latest issue can be found at http://gazette.call-cc.org or you can follow it in your feed reader at http://gazette.call-cc.org/feed.atom. If you'd like to write an issue, consult the wiki for the schedule and instructions!

The chicken image used in the logo is kindly provided and © 2010 by Manfred Wischner