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

site: faq: re-tell the history

Browse Source
This commit is contained in:
Simon Michael 2015-11-08 12:24:56 -08:00
parent 4723b36987
commit b52d5622a1
1 changed files with 73 additions and 132 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

205
site/faq.md
View File

@ -2,70 +2,65 @@
# Frequently asked questions # Frequently asked questions
## hledger and Ledger ## hledger & Ledger
### How does hledger relate to Ledger ? ### History
hledger was inspired by John Wiegley's I was a happy user of John Wiegley's [Ledger](http://ledger-cli.org)
[Ledger](http://ledger-cli.org). It is a friendly, mostly compatible (begun in 2003) for some time. There was a long period of stagnation
rewrite of Ledger in Haskell, begun in 2007 (Ledger started in 2003), in that project. I grew tired of bugs, missing and wrong documentation,
focussing on robustness, usability, ease of development, long-term and explaining the situation to confused newcomers.
maintainability, and new experiments such as the I really, truly needed a reliable accounting tool.
[web interface](manual.html#web). It currently lacks some of Ledger's I really didn't want to spend time learning C++.
power-user features and speed. hledger stays compatible with Ledger
wherever possible, so that with a little care you can use both tools
on the same data files.
Longer answer: I was a happy Ledger user and contributor for some I felt Ledger could be implemented well and perhaps even more
time, then became too dissatisfied with bugs, missing/wrong successfully in the Haskell programming language, which has some
documentation and a long period of stagnation. I also wanted to try compelling advantages. (It encourages the coding style known as pure
implementing Ledger's brilliant design in the Haskell programming functional programming, allowing more bug-free, concise and
language and ecosystem, which I believe has compelling advantages. I maintainable software. It provides a more abstracted, portable
try to build on Ledger's experience to make hledger easier to learn platform making installation easier. It is attractive for contributors
and use, better documented, more appealing to work on; and to provide to work on.)
alternate user interfaces (interactive, curses, web) to make it useful
to more people.
hledger builds quickly and has a complete and accurate manual, an I couldn't ask John to start over - back then he was not the Haskell
easier report query syntax, a data entry assistant, an optional web lover he has since become! - so in 2007 I started prototyping a
interface (which often works on Ledger files too), and multi-column parser, and kept going. My goals were to (a) learn how well Haskell
balance reports. Ledger has additional power-user features (capital could do in this (simple, thought I) real-world application, and (b)
gains tracking, periodic and modifier transactions, budget reports, maybe, build on Ledger's experience to create a new implementation
custom value expressions..) and it remains faster and more memory prioritising ease of use. It would have simpler features, fewer bugs,
efficient (for now!). better documentation, and additional user interfaces.
The two projects collaborate freely. For some time we shared the Later the Ledger project revived and attracted more contributors. The
[#ledger](irc://irc.freenode.net/#ledger) IRC channel; in 2014 I added two projects collaborate freely and ideas have travelled in both
a dedicated [#hledger](irc://irc.freenode.net/#hledger) channel. directions. Having two independent somewhat-compatible
I give back to Ledger by providing infrastructure implementations has been quite helpful for testing and
([ledger-cli.org](http://ledger-cli.org)), IRC support, [LedgerTips](http://twitter.com/LedgerTips) etc. troubleshooting, exploring the design space, and growing the "*ledger"
community. I also give back to Ledger by providing infrastructure
like [ledger-cli.org](http://ledger-cli.org),
[LedgerTips](http://twitter.com/LedgerTips), IRC support on #ledger
etc.
### And Ledger 4 ? For some time hledger shared Ledger's IRC channel #ledger. In 2014 I
added the dedicated [#hledger](irc://irc.freenode.net/#hledger)
channel.
There is also a [ledger4](https://github.com/ledger/ledger4) on github; this is ### Future ?
John's own rewrite of the core of
Ledger 3 in haskell. It's an early library prototype, not a usable tool.
Perhaps some day hledger or something like it would use this as its foundation.
### File format differences ? There is a [ledger4](https://github.com/ledger/ledger4) repo on
github; this is John's 2012/2013 rewrite of some parts of Ledger 3,
including the parser, in Haskell. We have a plan to add this parser to
hledger in 2015/2016, increasing its ability to read Ledger's files.
hledger's file format is mostly identical with Ledger's, by design. ### Features
Generally, it's easy to keep a journal file that works with both hledger
and Ledger if you avoid Ledger's and hledger's more specialised syntax
(or keep it in separate files which you include only when appropriate).
Some Ledger syntax is parsed but ignored (such as Compared to Ledger, hledger builds quickly and has a complete and
[automated transactions](http://ledger-cli.org/3.0/doc/ledger3.html#Automated-Transactions), [periodic transactions](http://ledger-cli.org/3.0/doc/ledger3.html#Periodic-Transactions), and accurate manual, an easier report query syntax, multi-column balance
[historical prices](manual.html#historical-prices)). reports, better depth limiting, an interactive data entry assistant,
Some features are not currently parsed and will cause an error, eg and optional web and curses interfaces.
Ledger's more recent top-level directives. There can also be subtle
differences in parser behaviour, such as with
[hledger comments](manual.html#comments) vs [Ledger comments](http://ledger-cli.org/3.0/doc/ledger3.html#Commenting-on-your-Journal),
or [balance assertions](manual.html#assertions-and-ordering).
### Feature differences ? Compared to hledger, Ledger has additional power-user features such as
periodic and modifier transactions, budget reports, and the built in
hledger mimics a subset of [Ledger 3.x](http://ledger-cli.org), and adds some features of its own. value expressions language, and it remains faster and more memory
efficient (for now).
We currently support: We currently support:
@ -74,19 +69,17 @@ We currently support:
- timelog format - timelog format
- regular journal transactions - regular journal transactions
- multiple commodities - multiple commodities
- fixed prices - fixed transaction prices
- varying market prices
- virtual postings - virtual postings
- print, register & balance commands
- filtering by many criteria, with different query syntax
- display expressions containing just a simple date predicate
- some basic output formatting - some basic output formatting
- the print, register & balance commands
- report filtering, using a different query syntax
We do not support: We do not support:
- automated transactions - automated transactions
- value expressions - value expressions
- fluctuating prices and historical price records
- display formats other than `d>[DATE]` or similar
- budget reports - budget reports
And we add these commands: And we add these commands:
@ -98,67 +91,26 @@ And we add these commands:
- incomestatement - incomestatement
- irr - irr
- interest - interest
- vty - ui
- web - web
### Option/command differences ? ### File formats
Ledger options and commands not supported include: hledger's journal file format is mostly identical with Ledger's, by design.
``` Generally, it's easy to keep a journal file that works with both hledger
Basic options: and Ledger if you avoid Ledger's and hledger's more specialised syntax
-o, --output FILE write output to FILE (or keep it in separate files which you include only when appropriate).
-i, --init-file FILE initialize ledger using FILE (default: ~/.ledgerrc)
-a, --account NAME use NAME for the default account (useful with QIF)
Report filtering: Some Ledger syntax is parsed but ignored (such as
-c, --current show only current and past entries (not future) [automated transactions](http://ledger-cli.org/3.0/doc/ledger3.html#Automated-Transactions)
--period-sort EXPR sort each report period's entries by EXPR and [periodic transactions](http://ledger-cli.org/3.0/doc/ledger3.html#Periodic-Transactions)).
-L, --actual consider only actual (non-automated) transactions Some features are not currently parsed and will cause an error, eg
--budget generate budget entries based on periodic entries Ledger's more recent top-level directives. There can also be subtle
--add-budget show all transactions plus the budget differences in parser behaviour, such as with
--unbudgeted show only unbudgeted transactions [hledger comments](manual.html#comments) vs [Ledger comments](http://ledger-cli.org/3.0/doc/ledger3.html#Commenting-on-your-Journal),
--forecast EXPR generate forecast entries while EXPR is true or [balance assertions](manual.html#assertions-and-ordering).
-l, --limit EXPR calculate only transactions matching EXPR
-t, --amount EXPR use EXPR to calculate the displayed amount
-T, --total EXPR use EXPR to calculate the displayed total
Output customization: ### Functional differences
-n, --collapse Only show totals in the top-most accounts.
-P, --by-payee show summarized totals by payee
-x, --comm-as-payee set commodity name as the payee, for reporting
--dow show a days-of-the-week report
-S, --sort EXPR sort report according to the value expression EXPR
--head COUNT show only the first COUNT entries (negative inverts)
--tail COUNT show only the last COUNT entries (negative inverts)
--pager PAGER send all output through the given PAGER program
-A, --average report average transaction amount
-D, --deviation report deviation from the average
-%, --percentage report balance totals as a percentile of the parent
--totals in the "xml" report, include running total
-j, --amount-data print only raw amount data (useful for scripting)
-J, --total-data print only raw total data
-y, --date-format STR use STR as the date format (default: %Y/%m/%d)
--balance-format --register-format --print-format
--plot-amount-format --plot-total-format --equity-format
--prices-format --wide-register-format
Commodity reporting:
--price-db FILE sets the price database to FILE (def: ~/.pricedb)
-L, --price-exp MINS download quotes only if newer than MINS (def: 1440)
-Q, --download download price information when needed
-O, --quantity report commodity totals (this is the default)
-V, --market report last known market value
-g, --performance report gain/loss for each displayed transaction
-G, --gain report net gain/loss
Commands:
xml [REGEXP]... print matching entries in XML format
equity [REGEXP]... output equity entries for matching accounts
prices [REGEXP]... display price history for matching commodities
entry DATE PAYEE AMT output a derived entry, based on the arguments
```
### Other functionality differences ?
- hledger recognises description and negative patterns by "desc:" - hledger recognises description and negative patterns by "desc:"
and "not:" prefixes, unlike Ledger 3's free-form parser and "not:" prefixes, unlike Ledger 3's free-form parser
@ -175,9 +127,6 @@ entry DATE PAYEE AMT output a derived entry, based on the arguments
- hledger splits multi-day timelog sessions at midnight by default (Ledger does this with an option) - hledger splits multi-day timelog sessions at midnight by default (Ledger does this with an option)
- hledger doesn't track the value of commodities with varying
price; prices are fixed as of the transaction date
- hledger's output follows the decimal point character, digit grouping, - hledger's output follows the decimal point character, digit grouping,
and digit group separator character used in the journal. and digit group separator character used in the journal.
@ -199,31 +148,23 @@ entry DATE PAYEE AMT output a derived entry, based on the arguments
taking it from the clock-out entry taking it from the clock-out entry
- hledger's [include directive](manual.html#including-other-files) does not support - hledger's [include directive](manual.html#including-other-files) does not support
shell glob patterns (eg `include *.journal` ), which Ledger does. shell glob patterns (eg `include *.journal` ), which Ledger's does.
- when checking [balance assertions](manual.html#balance-assertions) - when checking [balance assertions](manual.html#balance-assertions)
hledger sorts the account's postings first by date and then (for hledger sorts the account's postings first by date and then (for
postings with the same date) by parse order. Ledger goes strictly by postings with the same date) by parse order. Ledger goes strictly by
parse order. parse order.
- Ledger allows amounts to have a - Ledger allows amounts to have a fixed lot price (the {} syntax ?)
[fixed lot price](manual.html#fixed-lot-prices) and a regular price in any and a regular price in any order (and uses whichever appears
order (and uses whichever appears first). hledger requires the fixed first). hledger requires the fixed lot price to come last (and
lot price to come last (and ignores it). ignores it).
### Implementation differences ?
Ledger is written in C++, whereas hledger is written in [Haskell](http://haskell.org).
Haskell is a highly regarded up-and-coming programming language that enables
a coding style known as pure functional programming, offering the
promise of more bug-free and maintainable software built in fewer
lines of code. Haskell also provides a more abstracted, portable
platform which can make deployment and installation easier in some
cases.
## UI surprises ## UI surprises
### Why does it complain about missing amounts ? I put one there ### Why does it complain about missing amounts even though I wrote one ?
This is an easy mistake at first. This journal entry: This is an easy mistake at first. This journal entry:
```journal ```journal