hledger/doc/haskellerz/haskellerz.md

% Inside hledger: an architectural tour and how-to % Simon Michael % April 29, 2021

Introductions

0:00 (10m)

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

Architecture

0:10 (25m)

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

How to..

0:35 (25m)

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

Q & A

1:00 (30m)

End

1:30

$ git shortlog -s
Aerex
Aiken Cairncross
Alejandro García Montoro
Aleksandar Dimitrov
Alex Chen
Alvaro Fernando García
Amarandus
Amitai Burstein
Andreas Pauley
Andrew Jones
Andriy Mykhaylyk
Arnout Engelen
Ben Boeckel
Ben Creasy
Boyd Kelly
Brian Scott
Brian Wignall
Bryan Richter
Caleb Maclennan
Carel Fellinger
Carl Richard Theodor Schneider
Carlos Lopez-Camey
Christian G. Warden
Christoph Nicolai
Clint Adams
Colin Woodbury
Damien Cassou
David Reaver
David Zhang
Dmitry Astapov
Dominik Süß
Doug Goldstein
Eli Flanagan
Elijah Caine
Eric Kow
Eric Mertens
Everett Hildenbrandt
Evilham
Felix Van der Jeugt
Felix Yan
Fun Ilrys (Nissar Chababy)
Gabriel Ebner
Gaith Hallak
Gergely Risko
Hans-Peter Deifel
Henning Thielemann
Imuli
Jacek Generowicz
Jacob Weisz
Jakob Schöttl
Jakub Zárybnický
Jan Zerebecki
Jeff Richards
Jesse Rosenthal
Joachim Breitner
Joe Horsnell
Johann Klähn
Johannes Gerer
John Wiegley
Joseph Weston
Joshua Chia
Joshua Kehn
Judah Jacobson
Julien Moutinho
Justin Le
Kyle Marek-Spartz
Luca Molteni
Léo Gaspard
M Parker
Malte Brandy
Mark Hansen
Marko Kocić
Martin Michlmayr
Mateus Furquim
Matthias Kauer
Max Bolingbroke
Michael Kainer
Michael Sanders
Michael Snoyman
Michael Walker
Mick Dekkers
Mitchell Rosen
Moritz Kiefer
Mykola Orliuk
Nadrieril
Nicholas Niro
Nick Ingolia
Nicolas Wavrant
Nikhil Jha
Nissar Chababy
Nolan Darilek
Oliver Braun
Omari Norman
Pavan Rikhi
Pavlo Kerestey
Peter Simons
Pia Mancini
Rick Lupton
Roman Cheplyaka
Rui Chen
Ryan Desfosses
Sam Doshi
Sam Jeeves
Samuel May
Sergei Trofimovich
Sergey Astanin
Shubham Lagwankar
Simon Hengel
Simon Michael
SpicyCat
Stefano Rodighiero
Stephen Morgan
Steven R. Baker
TANIGUCHI Kohei
Thomas R. Koll
Tim Docker
Timofey ZAKREVSKIY
Trygve Laugstøl
Vladimir Sorokin
Vladimir Zhelezov
Wad
Xinruo Sun
afarrow
agander
aragaer
awjchen
azure-pipelines[bot]
flip111
gwern
jeevcat
jungle-boogie
legrostdg
trevorriles
zieone