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

docs: move ledger compatibility docs into FAQ

Browse Source
This commit is contained in:
Simon Michael 2013-04-14 17:34:30 -07:00
parent 2d4c693288
commit 03e752969a
3 changed files with 177 additions and 183 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
DOCS.md
View File

@ -7,12 +7,11 @@ title: hledger docs
**Official hledger docs:** **Official hledger docs:**
[Installation Guide](INSTALL.html) and [Release Notes](NEWS.html)\ [Installation Guide](INSTALL.html) and [Release Notes](NEWS.html)\
**[User Manual](MANUAL.html)** (past releases: **[User Manual](MANUAL.html)** (past versions:
[0.19.x User Manual](0.19/MANUAL.html), [0.19.x manual](0.19/MANUAL.html),
[0.18.x User Manual](0.18/MANUAL.html))\ [0.18.x manual](0.18/MANUAL.html))\
[Developer Guide](DEVELOP.html)\ [Developer Guide](DEVELOP.html)\
[FAQ](FAQ.html) *in progress*\ [FAQ](FAQ.html)\
[Compatibility with ledger](LEDGER.html)\
**Tutorials:** **Tutorials:**

178
FAQ.md
View File

@ -4,10 +4,11 @@ title: hledger frequently asked questions
# Frequently asked questions # Frequently asked questions
## How does hledger relate to ledger ? ## hledger and ledger
hledger was inspired by and is partly a clone of John Wiegley's ### How does hledger relate to ledger ?
[ledger](http://ledger-cli.org) (also called "c++ ledger" here.)
hledger was inspired by and is partly a clone of John Wiegley's [ledger](http://ledger-cli.org).
I was a happy ledger user and contributor for some time; I still use it I was a happy ledger user and contributor for some time; I still use it
occasionally. I wrote hledger because I wanted to develop financial tools occasionally. I wrote hledger because I wanted to develop financial tools
@ -32,10 +33,177 @@ separate mail lists
to give back by providing infrastructure to give back by providing infrastructure
([ledger-cli.org](http://ledger-cli.org)) and IRC support. ([ledger-cli.org](http://ledger-cli.org)) and IRC support.
hledger stays compatible with ledger wherever possible, so that you hledger stays compatible with ledger wherever possible, so that you
can often use both tools on the same data file. Here is more about can often use both tools on the same data file.
[compatibility](LEDGER.html).
Summary: hledger is a friendly, co-evolving, compatible rewrite of ledger Summary: hledger is a friendly, co-evolving, compatible rewrite of ledger
in Haskell, lacking some of ledger's power features and raw performance, in Haskell, lacking some of ledger's power features and raw performance,
and focussing on robustness, usability, ease of development, and and focussing on robustness, usability, ease of development, and
experimental add-ons such as the [web interface](MANUAL.html#web). experimental add-ons such as the [web interface](MANUAL.html#web).
### What are the feature differences ?
hledger mimics a subset of [ledger 3.x](http://ledger-cli.org), and adds some features of its own.
We currently support:
- ledger's journal format, mostly
- csv format
- timelog format
- regular journal transactions
- multiple commodities
- fixed prices and price history
- 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
We do not support:
- automated transactions
- value expressions
- fluctuating prices
- display formats other than `d>[DATE]` or similar
- budget reports
And we add these commands:
- add
- balancesheet
- cashflow
- chart
- incomestatement
- irr
- interest
- vty
- web
ledger options and commands not supported include:
Basic options:
-o, --output FILE write output to FILE
-i, --init-file FILE initialize ledger using FILE (default: ~/.ledgerrc)
-a, --account NAME use NAME for the default account (useful with QIF)
Report filtering:
-c, --current show only current and past entries (not future)
--period-sort EXPR sort each report period's entries by EXPR
-L, --actual consider only actual (non-automated) transactions
--budget generate budget entries based on periodic entries
--add-budget show all transactions plus the budget
--unbudgeted show only unbudgeted transactions
--forecast EXPR generate forecast entries while EXPR is true
-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:
-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
### What are the file format differences ?
hledger's file format is mostly identical with ledger's, by design.
Generally, it's easy to keep a journal file that works with both hledger
and ledger if you avoid ledger's most advanced features.
Some ledger features are parsed but ignored, eg:
- automated transactions ( = ... , ~ ... )
- balance assertions ( AMT1=AMT2 )
- fixed lot prices ( {...} )
- historical prices ( P ... )
Some features are not currently parsed and will cause an error, eg:
- balance assignments
- some top level directives like "account"
There can also be subtle differences in parser behaviour, eg
comments may be permissible in different places.
### What other functionality differences are there ?
- hledger recognises description and negative patterns by "desc:"
and "not:" prefixes, unlike ledger 3's free-form parser
- hledger doesn't require a space before command-line option
values, eg `-fFILE` or `-f FILE` works
- hledger's weekly reporting intervals always start on mondays
- hledger shows start and end dates of the intervals requested,
not just the span containing data
- hledger always shows timelog balances in hours
- hledger splits multi-day timelog sessions at midnight
- 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,
and digit group separator character used in the journal.
- hledger print shows amounts for all postings, and shows unit prices for
amounts which have them. (This means that it does not currently print
multi-commodity transactions in valid journal format.)
- hledger print ignores the --date2 flag, always showing both dates.
ledger print shows only the secondary date with --aux-date, but not
vice versa.
- hledger's default commodity directive (D) sets the commodity for
subsequent commodityless amounts, and sets that commodity's display
settings if such an amount is the first seen. ledger uses D only for
commodity display settings and for the entry command.
- hledger generates a description for timelog sessions, instead of
taking it from the clock-out entry
- hledger's [include directive](MANUAL.html#including-other-files) does not support
shell glob patterns (eg `include *.journal` ), which ledger does.
### How are the implementations different ?
ledger is written in C++, whereas hledger is written in the
[Haskell](http://haskell.org) programming language.
Haskell is a highly regarded up-and-coming 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. Haskell also brings some new challenges such as managing memory
growth and laziness.

173
LEDGER.md
View File

@ -1,173 +0,0 @@
---
title: hledger Compatibility with ledger
---
# Compatibility with ledger
hledger mimics a subset of [ledger 3.x](http://ledger-cli.org), and adds some features of its own.
## Implementation
ledger is written in C++, whereas hledger is written in the
[Haskell](http://haskell.org) programming language.
Haskell is a 20+-year-old, up-and-coming 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. Haskell also brings some new challenges such as managing memory
growth and laziness.
## File format
hledger's file format is mostly identical with ledger's, by design.
Generally, it's easy to keep a journal file that works with both hledger
and ledger if you avoid ledger's most advanced features.
Some ledger features are parsed but ignored, eg:
- automated transactions ( = ... , ~ ... )
- balance assertions ( AMT1=AMT2 )
- fixed lot prices ( {...} )
- historical prices ( P ... )
Some features are not currently parsed and will cause an error, eg:
- balance assignments
- some top level directives like "account"
There can also be subtle differences in parser behaviour, eg
comments may be permissible in different places.
## Features
We currently support:
- ledger's journal format, mostly
- csv format
- timelog format
- regular journal transactions
- multiple commodities
- fixed prices and price history
- 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
We do not support:
- automated transactions
- value expressions
- fluctuating prices
- display formats other than `d>[DATE]` or similar
- budget reports
And we add these commands:
- add
- balancesheet
- cashflow
- chart
- incomestatement
- irr
- interest
- vty
- web
ledger options and commands not supported include:
Basic options:
-o, --output FILE write output to FILE
-i, --init-file FILE initialize ledger using FILE (default: ~/.ledgerrc)
-a, --account NAME use NAME for the default account (useful with QIF)
Report filtering:
-c, --current show only current and past entries (not future)
--period-sort EXPR sort each report period's entries by EXPR
-L, --actual consider only actual (non-automated) transactions
--budget generate budget entries based on periodic entries
--add-budget show all transactions plus the budget
--unbudgeted show only unbudgeted transactions
--forecast EXPR generate forecast entries while EXPR is true
-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:
-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
## Functionality
- hledger recognises description and negative patterns by "desc:"
and "not:" prefixes, unlike ledger 3's free-form parser
- hledger doesn't require a space before command-line option
values, eg `-fFILE` or `-f FILE` works
- hledger's weekly reporting intervals always start on mondays
- hledger shows start and end dates of the intervals requested,
not just the span containing data
- hledger always shows timelog balances in hours
- hledger splits multi-day timelog sessions at midnight
- 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,
and digit group separator character used in the journal.
- hledger print shows amounts for all postings, and shows unit prices for
amounts which have them. (This means that it does not currently print
multi-commodity transactions in valid journal format.)
- hledger print ignores the --date2 flag, always showing both dates.
ledger print shows only the secondary date with --aux-date, but not
vice versa.
- hledger's default commodity directive (D) sets the commodity for
subsequent commodityless amounts, and sets that commodity's display
settings if such an amount is the first seen. ledger uses D only for
commodity display settings and for the entry command.
- hledger generates a description for timelog sessions, instead of
taking it from the clock-out entry
- hledger's [include directive](MANUAL.html#including-other-files) does not support
shell glob patterns (eg `include *.journal` ), which ledger does.