slaesvuo/hledger
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

doc: sync latest manual/dev guide from wiki

Browse Source
This commit is contained in:
Simon Michael 2014-11-04 20:33:26 -08:00
parent 6b2dfb3d79
commit b045d6b530
2 changed files with 203 additions and 45 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

200
doc/developer-guide.md
View File

@ -4,23 +4,43 @@
## Quick links ## Quick links
**Released version:**\\ ^ hledger.org: ^ [[release notes|combined release notes]], [[download|pre-compiled binaries]] ^
[[Release notes]], ^ Github: ^ [code](http://github.com/simonmichael/hledger), [commits](http://github.com/simonmichael/hledger/commits), [COMMITS](http://starlogs.net/#simonmichael/hledger) (turn up your volume) \\ [commits only in master](https://github.com/simonmichael/hledger/compare/0.23...master), [commits only in release branch](https://github.com/simonmichael/hledger/compare/master...0.23) \\ [build status (hydra)](http://hydra.cryp.to/jobset/hledger/master#tabs-jobs) \\ [open bugs](https://github.com/simonmichael/hledger/issues?direction=desc&labels=BUG&page=1&sort=created&state=open), [all bugs](https://github.com/simonmichael/hledger/issues?direction=desc&labels=BUG&page=1&sort=created), [open issues](https://github.com/simonmichael/hledger/issues?direction=desc&labels=&page=1&sort=created&state=open), [all issues](https://github.com/simonmichael/hledger/issues?direction=desc&labels=&page=1&sort=created) ^
[[download|Downloads]]\\ ^ Hackage: ^ [hledger-lib](http://hackage.haskell.org/package/hledger-lib), [hledger](http://hackage.haskell.org/package/hledger), [hledger-web](http://hackage.haskell.org/package/hledger-web), [hledger-interest](http://hackage.haskell.org/package/hledger-interest), [hledger-irr](http://hackage.haskell.org/package/hledger-irr), [hledger-vty](http://hackage.haskell.org/package/hledger-vty), [hledger-chart](http://hackage.haskell.org/package/hledger-chart), [*hledger*](http://hackage.haskell.org/packages/search?terms=hledger) \\ reverse dependencies: [hledger-lib](http://packdeps.haskellers.com/reverse/hledger-lib), [hledger](http://packdeps.haskellers.com/reverse/hledger), [outdated dependencies](http://packdeps.haskellers.com/feed/?needle=hledger) \\ [download activity](http://best-haskell.herokuapp.com/#/category/Finance) ^
Hackage: ^ Stackage: ^ [hledger entry](https://github.com/fpco/stackage/blob/master/Stackage/Config.hs#L449-450), [issues](https://github.com/fpco/stackage/search?q=hledger&ref=cmdform&type=Issues) \\ [build status (jenkins)](http://jenkins.stackage.org/job/Stackage/), last build output: [7.4](http://jenkins.stackage.org/job/Stackage/ghcversion=7.4.2/lastBuild/console), [7.6](http://jenkins.stackage.org/job/Stackage/ghcversion=7.6.3/lastBuild/console), [7.8](http://jenkins.stackage.org/job/Stackage/ghcversion=7.8.2/lastBuild/console) ^
[hledger-lib](http://hackage.haskell.org/package/hledger-lib), ^ Debian: ^ source packages \\ [haskell-hledger-lib](http://packages.qa.debian.org/h/haskell-hledger-lib.html), [bugs](https://bugs.debian.org/cgi-bin/pkgreport.cgi?package=haskell-hledger-lib), [haskell-hledger](http://packages.qa.debian.org/h/haskell-hledger.html), [bugs](https://bugs.debian.org/cgi-bin/pkgreport.cgi?package=haskell-hledger), [haskell-hledger-web](http://packages.qa.debian.org/h/haskell-hledger-web.html), [bugs](https://bugs.debian.org/cgi-bin/pkgreport.cgi?package=haskell-hledger-web) \\ binary packages \\ testing: [hledger](https://packages.debian.org/testing/hledger), [bugs](https://bugs.debian.org/cgi-bin/pkgreport.cgi?package=hledger;dist=testing), [hledger-web](https://packages.debian.org/testing/hledger-web), [bugs](https://bugs.debian.org/cgi-bin/pkgreport.cgi?package=hledger-web;dist=testing) \\ unstable: [hledger](https://packages.debian.org/unstable/hledger), [bugs](https://bugs.debian.org/cgi-bin/pkgreport.cgi?package=hledger;dist=unstable), [hledger-web](https://packages.debian.org/unstable/hledger-web), [bugs](https://bugs.debian.org/cgi-bin/pkgreport.cgi?package=hledger-web;dist=unstable) \\ all: [*hledger*](https://packages.debian.org/search?searchon=names&keywords=hledger) \\ popularity stats: [hledger](https://qa.debian.org/popcon.php?package=haskell-hledger), [hledger-web](https://qa.debian.org/popcon.php?package=haskell-hledger-web) \\ [PTS help](https://www.debian.org/doc/manuals/developers-reference/resources.html#pkg-tracking-system) ^
[hledger](http://hackage.haskell.org/package/hledger), ^ Ubuntu: ^ source packages \\ [haskell-hledger-lib](https://launchpad.net/ubuntu/+source/haskell-hledger-lib), [bugs](https://bugs.launchpad.net/ubuntu/+source/haskell-hledger-lib), [haskell-hledger](https://launchpad.net/ubuntu/+source/haskell-hledger), [bugs](https://bugs.launchpad.net/ubuntu/+source/haskell-hledger), [haskell-hledger-web](https://launchpad.net/ubuntu/+source/haskell-hledger-web), [bugs](https://bugs.launchpad.net/ubuntu/+source/haskell-hledger-web) \\ binary packages \\ [*hledger*](http://packages.ubuntu.com/search?suite=all&searchon=names&keywords=hledger) ^
[hledger-web](http://hackage.haskell.org/package/hledger-web), ^ Gentoo: ^ [hledger](http://gpo.zugaina.org/dev-haskell/hledger), [hledger-web](http://gpo.zugaina.org/dev-haskell/hledger-web), [*hledger*](http://gpo.zugaina.org/Search?search=hledger) ^
[hledger-interest](http://hackage.haskell.org/package/hledger-interest), ^ Fedora: ^ [hledger](https://apps.fedoraproject.org/packages/hledger), [*hledger*](https://apps.fedoraproject.org/packages/s/hledger) ^
[hledger-irr](http://hackage.haskell.org/package/hledger-irr),
[hledger-vty](http://hackage.haskell.org/package/hledger-vty),
[hledger-chart](http://hackage.haskell.org/package/hledger-chart)\\
Debian: [haskell-hledger](http://packages.qa.debian.org/h/haskell-hledger.html)\\
Ubuntu: [haskell-hledger](https://launchpad.net/ubuntu/+source/haskell-hledger)\\
RedHat/Fedora: [hledger](http://fr2.rpmfind.net/linux/rpm2html/search.php?query=hledger&submit=Search+...)\\
Gentoo: [hledger](http://gpo.zugaina.org/Search?search=hledger)\\
<!-- <!-- list the debian packages for clarity:
3 source:
haskell-hledger-lib
haskell-hledger
haskell-hledger-web
8 binary:
hledger
hledger-web
libghc-hledger-dev
libghc-hledger-doc
libghc-hledger-prof
libghc-hledger-lib-dev
libghc-hledger-lib-doc
libghc-hledger-lib-prof
-->
<!-- old/future links -->
<!-- [haddock coverage](http://hledger.org/profs/haddock-coverage), -->
<!-- [unit test coverage](http://hledger.org/profs/coverage/hpc_index_fun.html), -->
<!-- [benchmark](http://hledger.org/profs/latest.bench) -->
<!-- [profile](http://hledger.org/profs/latest.prof), -->
<!-- [heap](http://hledger.org/profs/latest.ps) -->
<!-- [developer notes](http://github.com/simonmichael/hledger/NOTES.org)\ -->
<!-- [browse dev API docs](http://hledger.org/api/frames.html) -->
<!-- [[developer-guide#set-up-for-development|How to clone it]] -->
<!-- [hledger-web dev demo](http://demo.hledger.org:5001) -->
<!-- hoogle search form
<script type="text/javascript" src="http://haskell.org/hoogle/datadir/resources/jquery-1.4.2.js"></script> <script type="text/javascript" src="http://haskell.org/hoogle/datadir/resources/jquery-1.4.2.js"></script>
<script type="text/javascript" src="http://haskell.org/hoogle/datadir/resources/hoogle.js"></script> <script type="text/javascript" src="http://haskell.org/hoogle/datadir/resources/hoogle.js"></script>
<form action="http://haskell.org/hoogle/" method="get" style="display:inline; margin:0; padding:0;"> <form action="http://haskell.org/hoogle/" method="get" style="display:inline; margin:0; padding:0;">
@ -32,28 +52,9 @@ Gentoo: [hledger](http://gpo.zugaina.org/Search?search=hledger)\\
</form> </form>
--> -->
**Development version:**\\
[Commits](http://github.com/simonmichael/hledger/commits),
[COMMITS!](http://starlogs.net/#simonmichael/hledger) (turn up your volume),
[Code](http://github.com/simonmichael/hledger),
[[developer-guide#set-up-for-development|How to clone it]]
<!-- [hledger-web dev demo](http://demo.hledger.org:5001) -->
\\
Reports:
[build](http://hydra.cryp.to:8080/project/hledger),
[dependencies](http://packdeps.haskellers.com/feed/?needle=hledger)
<!-- [haddock coverage](http://hledger.org/profs/haddock-coverage), -->
<!-- [unit test coverage](http://hledger.org/profs/coverage/hpc_index_fun.html), -->
<!-- [benchmark](http://hledger.org/profs/latest.bench) -->
<!-- [profile](http://hledger.org/profs/latest.prof), -->
<!-- [heap](http://hledger.org/profs/latest.ps) -->
<!-- [developer notes](http://github.com/simonmichael/hledger/NOTES.org)\ -->
<!-- [browse dev API docs](http://hledger.org/api/frames.html) -->
--- ---
*2014: needs an update*
## Project overview ## Project overview
A rough overview/blueprint for the hledger project. A rough overview/blueprint for the hledger project.
@ -99,6 +100,11 @@ As of 2014/2, hledger.org is a wiki, and most docs are maintained as wiki pages.
Some, particularly the user manual and release notes, still exist in the main source repo as well. Some, particularly the user manual and release notes, still exist in the main source repo as well.
These should probably not be updated directly, instead they are copied from the wiki before each release. These should probably not be updated directly, instead they are copied from the wiki before each release.
### Code
The hledger repo is hosted on github.com: http://github.com/simonmichael/hledger.
(You can also jump there via [hledger.org/code[/commits]](http://hledger.org/code), or code.hledger.org[/commits]).
### Quality control ### Quality control
Relevant tools include: Relevant tools include:
@ -109,11 +115,17 @@ Relevant tools include:
- documentation tests (make haddocktest + manual) - documentation tests (make haddocktest + manual)
- ui tests (manual) - ui tests (manual)
- installation tests (manual) - installation tests (manual)
- code reviews
### Code ### Code reviews
We held a code review party, hopefully the first of many, in July 2014 on the mail list and IRC channel.
Here's the original [proposal](http://article.gmane.org/gmane.comp.finance.ledger.hledger/1070) giving some motivation, and the discussion logs, note these are a good source of hledger development tips:
- 2014/7/21-25 **hledger-web code & UI**
[mail thread](http://thread.gmane.org/gmane.comp.finance.ledger.hledger/1070),
[IRC log](http://hledger.org/static/irc-20140725-code-review.html)
- the hledger repo is hosted on github.com: http://github.com/simonmichael/hledger.
(You can also jump there via [hledger.org/code](http://hledger.org/code) or code.hledger.org).
<!-- ### release process --> <!-- ### release process -->
@ -129,7 +141,23 @@ Relevant tools include:
<!-- ### contributors and credits --> <!-- ### contributors and credits -->
### Data model ---
## Implementation notes
### hledger
There are two core cabal packages:
**[hledger-lib](http://hackage.haskell.org/package/hledger-lib)** - data model, parsing, manipulation, standard reports
([github](https://github.com/simonmichael/hledger/tree/master/hledger-lib))\\
**[hledger](http://hackage.haskell.org/package/hledger)** - command line interface, reusable cli options & helpers
([github](https://github.com/simonmichael/hledger/tree/master/hledger))
Most data types are defined in hledger-lib:Hledger.Data.Types,
while functions that operate on them are defined in
hledger-lib:Hledger.Data.TYPENAME.
Here's a diagram of the main data model:
<uml> <uml>
hide empty members hide empty members
@ -164,7 +192,101 @@ Amount -- Price
Amount -- AmountStyle Amount -- AmountStyle
</uml> </uml>
hledger parses the journal file into a
[Journal](http://hackage.haskell.org/package/hledger-lib-0.23.2/docs/Hledger-Data-Types.html#t:Journal),
which contains a list of
[Transactions](http://hackage.haskell.org/package/hledger-lib-0.23.2/docs/Hledger-Data-Types.html#t:Transaction),
each containing multiple
[Postings](http://hackage.haskell.org/package/hledger-lib-0.23.2/docs/Hledger-Data-Types.html#t:Posting)
of some
[MixedAmount](http://hackage.haskell.org/package/hledger-lib-0.23.2/docs/Hledger-Data-Types.html#t:MixedAmount)
(multiple
single-[Commodity](http://hackage.haskell.org/package/hledger-lib-0.23.2/docs/Hledger-Data-Types.html#t:Commodity)
[Amounts](http://hackage.haskell.org/package/hledger-lib-0.23.2/docs/Hledger-Data-Types.html#t:Amount))
to some
[AccountName](http://hackage.haskell.org/package/hledger-lib-0.23.2/docs/Hledger-Data-Types.html#t:AccountName).
Commands get and render
[Reports](http://hackage.haskell.org/package/hledger-lib-0.23.2/docs/Hledger-Reports.html)
from the Journal, or sometimes from a
[Ledger](http://hackage.haskell.org/package/hledger-lib-0.23.2/docs/Hledger-Data-Types.html#t:Ledger),
which contains
[Accounts](http://hackage.haskell.org/package/hledger-lib-0.23.2/docs/Hledger-Data-Types.html#t:Account)
representing the summed balances and other details of each account.
After surveying the packages, modules, and data types, try tracing the execution of a hledger command:
1. CLI stuff is in [hledger:Hledger.Cli](https://github.com/simonmichael/hledger/tree/master/hledger/Hledger/Cli).
2. [hledger:Hledger.Cli.Main:main](https://github.com/simonmichael/hledger/blob/master/hledger/Hledger/Cli/Main.hs#L179)
parses the command line to select a command, then
3. gives it to
[hledger:Hledger.Cli.Utils:withJournalDo](https://github.com/simonmichael/hledger/blob/master/hledger/Hledger/Cli/Utils.hs#L61),
which runs it after doing all the initial parsing.
4. Parsing code is under
[hledger-lib:Hledger.Read](https://github.com/simonmichael/hledger/tree/master/hledger-lib/Hledger/Read.hs),
eg the
[hledger-lib:Hledger.Read.JournalReader](https://github.com/simonmichael/hledger/tree/master/hledger-lib/Hledger/Read/JournalReader.hs).
5. Commands extract useful information from the parsed data model using
[hledger-lib:Hledger.Reports](https://github.com/simonmichael/hledger/tree/master/hledger-lib/Hledger/Reports),
and
6. render it to the console.
7. Everything uses the types and data
utilities under
[hledger-lib:Hledger.Data](https://github.com/simonmichael/hledger/tree/master/hledger-lib/Hledger/Data),
and the general helpers from
[hledger-lib:Hledger.Utils](https://github.com/simonmichael/hledger/blob/master/hledger-lib/Hledger/Utils.hs)
and below.
### hledger-web
hledger-web is in a third cabal package:
**[hledger-web](http://hackage.haskell.org/package/hledger-web)** - web interface
([github](https://github.com/simonmichael/hledger/tree/master/hledger-web))
It is a single-executable web application using the
[yesod](http://yesodweb.com) framework. It runs a built-in web server
serving some views of the journal file, reading it at startup and
again whenever it changes. It can also append new transactions to the journal file.
There are two main views, which can be filtered with [[manual#query-arguments|query arguments]]:
- [/journal](http://demo.hledger.org/journal), showing general journal entries (like `hledger print`)
- [/register](http://demo.hledger.org/register?q=inacct:Assets:Bank:Checking),
showing transactions affecting an account (slightly different from
`hledger register`, which shows postings).
There is also:
- a sidebar (toggled by pressing `s`) showing the chart of accounts (like `hledger balance`)
- an [add form](http://demo.hledger.org/journal?add=1) for adding new transactions (press `a`)
- a help dialog showing quick help and keybindings (press `h` or click ?)
Most of the action is in
- [config/routes](https://github.com/simonmichael/hledger/tree/master/hledger-web/config/routes)
- [templates/default-layout-wrapper.hamlet](https://github.com/simonmichael/hledger/tree/master/hledger-web/templates/default-layout-wrapper.hamlet)
- [Foundation](https://github.com/simonmichael/hledger/tree/master/hledger-web/Foundation.hs)
- [Handler.*](https://github.com/simonmichael/hledger/tree/master/hledger-web/Handler)
- [static/hledger.js](https://github.com/simonmichael/hledger/tree/master/hledger-web/static/hledger.js)
- [static/hledger.css](https://github.com/simonmichael/hledger/tree/master/hledger-web/static/hledger.css)
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.
The quickest way to test changes is `make ghciweb`, `:main --serve`, control-C, `:r`, repeat.
No linking is required, and changes to static files like hledger.js are visible after reloading a page.
Another way is `yesod devel`, which rebuilds automatically when files
change, including config files, templates and static files (but only in the hledger-web package).
A third way is `make autoweb`, if you can get it working (see the
makefile for instructions). This rebuilds automatically when haskell
files change in any of the hledger{-lib,,-web} packages.
---
## How to.. ## How to..

48
doc/manual.md
View File

@ -249,8 +249,11 @@ commodity. Amount styles include:
- the decimal point character (period or comma) - the decimal point character (period or comma)
- the display precision (number of decimal places displayed) - the display precision (number of decimal places displayed)
The canonical style is generally the style of the first posting amount seen in a commodity The canonical style is generally the style of the first posting amount seen in a commodity.
The precision is the highest precision seen among all posting amounts in the commmodity. However the display precision will be the highest precision seen in all posting amounts in that commmodity.
The precisions used in a price amount, or a D directive, don't affect the canonical display precision directly, but they can affect it indirectly, eg when D's default commodity is applied to a commodity-less amount or when an amountless posting is balanced using a price's commodity (actually this last case does not influence the canonical display precision but probably should).
##### Balance Assertions ##### Balance Assertions
@ -410,14 +413,14 @@ Some examples:
#### Tags #### Tags
You can include *tags* (labels), optionally with values, You can include *tags* (labels), optionally with values,
in transaction and posting comments, and then [query by tag](#queries). in transaction and posting comments, and then [[manual#query-arguments|query by tag]].
This is like Ledger's [metadata](http://ledger-cli.org/3.0/doc/ledger3.html#Metadata) This is like Ledger's [metadata](http://ledger-cli.org/3.0/doc/ledger3.html#Metadata)
feature, except hledger's tag values are simple strings. feature, except hledger's tag values are simple strings.
A tag is any unspaced word immediately followed by a full colon, eg: `sometag:` . A tag is any unspaced word immediately followed by a full colon, eg: `sometag:` .
A tag's *value* is the text following the colon, if any, until the next newline or comma, A tag's *value* is the characters following the colon, if any, until the next comma or newline,
with leading and trailing whitespace removed. Comma may be used to write multiple with any leading and trailing whitespace removed.
tags on one line. Comma may be used to write multiple tags on one line.
For example, here is a transaction with three tags, the posting has For example, here is a transaction with three tags, the posting has
one, and all tags have values except TAG1: one, and all tags have values except TAG1:
@ -426,6 +429,11 @@ one, and all tags have values except TAG1:
; TAG3: a third transaction tag ; TAG3: a third transaction tag
a $1 ; TAG4: a posting tag a $1 ; TAG4: a posting tag
**Things to note:**
In the journal file, a hledger tag value can contain: text, internal whitespace, or punctuation, but not: commas, newlines, or leading/trailing whitespace (putting quotes around it doesn't work, but probably should).
In [[manual#query-arguments|tag queries]], remember the tag name must match exactly, while the value part is the usual case-insensitive infix regular expression match.
#### Directives #### Directives
##### Account aliases ##### Account aliases
@ -988,6 +996,9 @@ More typically, use it to see a specific account's activity:
$ hledger register assets:bank:checking $ hledger register assets:bank:checking
The `--historical`/`-H` flag adds the balance from any prior postings
to the running total, to show the actual running account balance.
The `--depth` option limits the amount of sub-account detail displayed: The `--depth` option limits the amount of sub-account detail displayed:
$ hledger register assets:bank:checking --depth 2 $ hledger register assets:bank:checking --depth 2
@ -1429,6 +1440,31 @@ Examples:
--> -->
## Editor support
Add-on modes exist for various text editors, to make working with journal
files easier. They add colour, navigation aids and helpful commands.
For hledger users who edit the journal file directly (the majority),
using one of these modes is quite recommended.
These were written with Ledger in mind, but also work with hledger files:
| Emacs | http://www.ledger-cli.org/3.0/doc/ledger-mode.html |
| Vim | https://github.com/ledger/ledger/wiki/Getting-started-with-Vim |
| Sublime Text | https://github.com/ledger/ledger/wiki/Using-Sublime-Text |
| Textmate | https://github.com/ledger/ledger/wiki/Using-TextMate-2 |
| Text Wrangler | https://github.com/ledger/ledger/wiki/Editing-Ledger-files-with-TextWrangler |
<!-- Some related LedgerTips:
https://twitter.com/LedgerTips/status/504061626233159681
https://twitter.com/LedgerTips/status/502820400276193280
https://twitter.com/LedgerTips/status/502503912084361216
https://twitter.com/LedgerTips/status/501767602067472384
-->
## Known limitations ## Known limitations
Here are some things to be aware of. Here are some things to be aware of.