% 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.\ 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. ## 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 - ## What's hledger ? A suite of tools, file formats, and documentation for doing "plain text accounting". ## 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 * ## 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 * # 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 ```