Who am I ?

Simon Michael
Independent software consultant and developer.
https://joyful.com

Started in the home computer era (Ireland, 80s). ZX-80, Pet, VIC, C64, Amiga, PC, Mac, VAX/VMS, unix..

FOSS fan, contributor, project leader. Two big projects:

• Zwiki, 1996-2006, wiki engine, Python/Zope

• hledger, 2006-present, accounting tool, Haskell

Overview of talk

• A quick intro to plain text accounting and hledger. (10m)

• A tour of hledger’s architecture, codebase, evolutions, and design principles. (25m)

• How to script and develop hledger: custom commands, calling from other apps, troubleshooting, bug investigation, effective pull requests. (25m)

• Q&A to go deeper on whatever you like. (30m)

What’s Plain Text Accounting ?

A name I proposed (and a website I built) to help unify and grow the communities around Ledger, hledger, Beancount and similar accounting tools.

https://plaintextaccounting.org

The PTA ecosystem

The “big three” apps:

• Ledger - John Wiegley’s pioneering command line accounting app, inspiration for all the rest.
  C++, 2003-present

• hledger - Simon Michael’s rewrite/remix.
  Haskell, 2007-present

• Beancount - Martin Blais’ variant.
  Python, 2008-present

Many more apps and add-on tools - https://plaintextaccounting.org/#software

What’s hledger ?

A suite of tools, file formats, and documentation for doing “plain text accounting”.

https://hledger.org

hledger project goals

I was a Ledger user and new Haskeller. I started hledger with many goals:

• acquire a more robust, usable, evolving incarnation of Ledger
• develop a consistent, effective accounting habit
• get better at Haskell
• find out if Haskell was good for end-user apps and maintainer productivity
• grow a useful, long-lasting, financially sustainable FOSS accounting project

An end-user Haskell application

hledger is something that’s not yet common:

An end user application (ie: not a programming tool), written in Haskell, that aims to be

• easy to install,
• dependable,
• and pleasing to use,
• on all major platforms,
• by non-techies as well as power users.

A successful FOSS project

15 years, 134 contributors, 80-100 chatters, some number of happy users, useful to me every week.

Reasonably successful.

Not fulfilling my original goal of being financially self-sustaining and minimally time-consuming !

Tools

• hledger
• hledger-ui
• hledger-web
• hledger-iadd
• hledger-interest
• etc.

File formats

• journal
• csv
• timeclock
• timedot

Documentation

• introductory
• reference
• cookbook
• developer

A fast run through the evolution

• First commit
• First types
• First report
• Balance report
• Multi-column balance report
• Stateful parser
• Web interface
• Curses interface
• Package split
• Speed, features
• General currency conversion
• Valuation
• Always documentation

A tour of the codebase and project today (2021Q2)

Design principles

Script hledger

• https://hledger.org/scripting.html

Integrate hledger in your app

• Run cli, capture csv/json

• Run hledger-web, use http-json api

• Link with hledger-lib and/or other hledger packages, call public functions

Investigate a hledger bug

• Basic troubleshooting - docs, comparison, minimisation, reproduction, support

• Code debugging

How to submit a pull request

• https://hledger.org/CONTRIBUTING.html#pull-requests