hledger is a suite of applications, tools and libraries.
The main hledger code repository is github.com/simonmichael/hledger
There are also various hledger addons maintained as separate projects with their own repos.
Within the main repo, there are a number of separate cabal packages, making it easier to pick and choose parts of hledger to install or to package. They are:
Core data models, parsing, standard reports, and utilities. Most data types are defined in Hledger.Data.Types, while functions that operate on them are defined in Hledger.Data.TYPENAME. Under Hledger.Read are parsers for the supported input formats. Data files are parsed into a Journal, which contains a list of Transactions, each containing multiple Postings of some MixedAmount (multiple single-CommoditySymbol Amounts) to some AccountName. When needed, the Journal is further processed to derive a Ledger, which contains summed Accounts. In Hledger.Reports there are standard reports, which extract useful data from the Journal or Ledger.
Here's a diagram of the main data model:
hledger's command line interface, and command line options and utilities for other hledger tools.
Try tracing the execution of a hledger command:
- Hledger.Cli.Main:main parses the command line to select a command, then
- gives it to Hledger.Cli.Utils:withJournalDo, which runs it after doing all the initial parsing.
- Parsing code is under hledger-lib:Hledger.Read, eg Hledger.Read.JournalReader.
- Commands extract useful information from the parsed data model using hledger-lib:Hledger.Reports, and
- render in plain text for console output (or another output format, like CSV).
- Everything uses the data types and utilities from hledger-lib:Hledger.Data and hledger-lib:Hledger.Utils.
A terminal interface.
A web interface. hledger-web starts a web server built with the yesod framework, and (by default) opens a web browser view on it. It reads the journal file(s) at startup and again whenever they change. It can also write (append) new transactions to the journal file.
There are two main views, which can be filtered with queries:
/journal, showing general journal entries (like
There is also:
- a sidebar (toggled by pressing
s) showing the chart of accounts (like
- an add form for adding new transactions (press
- a help dialog showing quick help and keybindings (press
hor click ?)
Most of the action is in
Handler module and function names end with R, like the yesod-generated route type they deal with.
Dynamically generated page content is mostly inline hamlet. Lucius/Julius files and widgets generally are not used, except for the default layout.
Here are some ways to run it during development:
yesod devel: runs in developer mode, rebuilds automatically when config, template, static or haskell files change (but only files in the hledger-web package):
$ (cd hledger-web; yesod devel)
yesod-fast-devel may be a good alternative, also reloads the browser page
stack ghci: runs the server in developer mode from GHCI. Changes to static files like hledger.js will be visible on page reload; to see other changes, restart it as shown.
$ (cd hledger-web; stack ghci hledger-web) hledger-web> :main --serve # restart: ctrl-c, :r, enter, ctrl-p, ctrl-p, enter
make ghci-web: runs the server in developer mode from GHCI, also interprets the hledger-lib and hledger packages so that :reload picks up changes in those packages too:
$ make ghci-web ghci> :main --serve
(This rule also creates symbolic links to hledger-web's
directories, needed in developer mode, so it can run from the top directory. This may not work on Windows.)
Relevant tools include:
- unit tests (HUnit, make unittest)
- functional tests (shelltestrunner, make functest)
- performance tests (simplebench, make bench)
- documentation tests (make haddocktest + manual)
- ui tests (manual)
- installation tests (manual)
- code reviews