simonmichael/hledger
1
1
Fork 0
mirror of https://github.com/simonmichael/hledger.git synced 2024-12-26 03:42:25 +03:00
Code Issues Projects Releases Wiki Activity
0e9650d816
hledger/doc/CODE.md
Simon Michael 5dee1fe78c ;doc: move most dev docs to doc/
2022-12-04 11:22:05 -08:00

9.1 KiB
Raw Blame History

Code

hledger is a suite of applications, tools and libraries. The main hledger code repository is github.com/simonmichael/hledger (shortcut url code.hledger.org). There are also various hledger addons maintained as separate projects with their own repos.

hledger packages

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:

hledger-lib

package, code

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:

diagram

hledger

package, code, manual

hledger's command line interface, and command line options and utilities for other hledger tools.

Try tracing the execution of a hledger command:

  1. Hledger.Cli.Main:main parses the command line to select a command, then
  2. gives it to Hledger.Cli.Utils:withJournalDo, which runs it after doing all the initial parsing.
  3. Parsing code is under hledger-lib:Hledger.Read, eg Hledger.Read.JournalReader.
  4. Commands extract useful information from the parsed data model using hledger-lib:Hledger.Reports, and
  5. render in plain text for console output (or another output format, like CSV).
  6. Everything uses the data types and utilities from hledger-lib:Hledger.Data and hledger-lib:Hledger.Utils.

hledger-ui

package, code, manual

A terminal interface.

hledger-web

package, code, manual

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 hledger print)

  • /register, showing transactions affecting an account (slightly different from hledger's register command, which shows postings).

There is also:

  • a sidebar (toggled by pressing s) showing the chart of accounts (like hledger balance)
  • an add form for adding new transactions (press a)
  • a help dialog showing quick help and keybindings (press h or 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 config, messages, static and templates directories, needed in developer mode, so it can run from the top directory. This may not work on Windows.)

Quality

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

Code review