hledger/README

hledger - a ledger-compatible text-based accounting tool
========================================================

Welcome to hledger! 

hledger is a partial haskell clone of John Wiegley's text-based accounting
tool, ledger (http://wiki.github.com/jwiegley/ledger).  

hledger generates ledger-compatible register & balance reports from a
plain text journal, and demonstrates a functional implementation of
ledger.  

For more information, see http://hledger.org .

Copyright (c) 2007-2009 Simon Michael <simon@joyful.com>
Released under GPL version 3 or later.


Installation
------------
Building hledger requires GHC (http://haskell.org/ghc); it is known to
build with GHC 6.8 and up. hledger should work on any platform which GHC
supports.

Also, installing hledger easily requires the "cabal" command-line tool,
version 0.6.0 and up (http://www.haskell.org/cabal/download.html). (You
can also manually download and install each dependency mentioned in
hledger.cabal from hackage.org, but installing cabal is much quicker.)

Here's how to download and install the latest hledger release::

 cabal update
 cabal install hledger

Or, to build with all optional features enabled (downloads additional
dependencies)::

 cabal install --flags="happs vty" hledger

The available flags are::

  happs - enable the built-in webserver
  vty   - enable the curses text ui
  ansi  - enable the ansi text ui (use instead of vty on MS windows)

And for developers, here's how to get the latest development code::

 darcs get http://joyful.com/repos/hledger


Usage
-----
hledger looks for your ledger file at ~/.ledger by default. To use a
different file, specify it with the LEDGER environment variable or -f
option (which may be - for standard input). Here are some commands to try::

 hledger --help
 hledger -f sample.ledger balance
 export LEDGER=sample.ledger
 hledger -s balance
 hledger register
 hledger reg cash
 hledger reg -- shop
 hledger ui


Time reporting
--------------
hledger can parse a timelog file in timeclock.el's format, treating
time categories as accounts. If hledger is invoked by the "hours"
alias it looks for your timelog (~/.timelog, or the file specified by
$TIMELOG or -f), and parses arguments slightly differently for
convenient querying::

 hours [OPTIONS] [PERIOD [COMMAND [PATTERNS]]]

PERIOD and COMMAND default to "today" and "balance --subtotal" respectively.
Examples::

 hours                                 # today's balances
 hours today                           # the same
 hours 'this week'                     # so far this week
 hours week                            # the same
 hours lastmonth                       # last month, the space is optional
 hours 'from 1/15'                     # from jan 15
 hours 'monthly in 2008' reg --depth 1 # monthly register, top-level only

Features
--------

This version of hledger mimics a subset of ledger 2.6.1, and adds some
features of its own. We currently support: the balance, print, and
register commands, regular ledger entries, multiple commodities, virtual
transactions, account and description patterns, the LEDGER environment
variable, and these options::

   Basic options:
   -h, --help             display summarized help text
   -v, --version          show version information
   -f, --file FILE        read ledger data from FILE
 
   Report filtering:
   -b, --begin DATE       set report begin date
   -e, --end DATE         set report end date
   -p, --period EXPR      report using the given period
   -C, --cleared          consider only cleared transactions
   -R, --real             consider only real (non-virtual) transactions
 
   Output customization:
   -n, --collapse         balance report: no grand total
   -d, --display EXPR     display only transactions matching EXPR (limited support)
   -E, --empty            balance report: show accounts with zero balance
   -s, --subtotal         balance report: show sub-accounts
 
   Commodity reporting:
   -B, --basis, --cost    report cost basis of commodities

   Commands:
   balance  [REGEXP]...   show balance totals for matching accounts
   register [REGEXP]...   show register of matching transactions
   print    [REGEXP]...   print all matching entries

We handle (almost) the full period expression syntax, and simple display
expressions consisting of a date predicate.  Also the following
hledger-specific features are supported::

   ui                     a simple curses-based text ui (unix platforms only)
   ansi                   an even more rudimentary ansi-based text ui
   web                    a simple web interface on port 5000
   --depth=N              balance report: maximum account depth to show

ledger features not supported
.............................

ledger features not yet supported include: modifier and periodic entries,
!include and other special directives, price history entries, parsing
gnucash files, and the following options::

   Basic options:
   -o, --output FILE      write output to FILE
   -i, --init-file FILE   initialize ledger using FILE (default: ~/.ledgerrc)
       --cache FILE       use FILE as a binary cache when --file is not used
       --no-cache         don't use a cache, even if it would be appropriate
   -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
   -U, --uncleared        consider only uncleared transactions
   -L, --actual           consider only actual (non-automated) transactions
   -r, --related          calculate report using related 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         register: collapse entries
   -s, --subtotal         other: show subtotals
   -P, --by-payee         show summarized totals by payee
   -x, --comm-as-payee    set commodity name as the payee, for reporting
   -W, --weekly           show weekly sub-totals
   -M, --monthly          show monthly sub-totals
   -Y, --yearly           show yearly sub-totals
       --dow              show a days-of-the-week report
   -S, --sort EXPR        sort report according to the value expression EXPR
   -w, --wide             for the default register report, use 132 columns
       --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)
   -F, --format STR       use STR as the format; for each report type, use:
       --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 differences
.................

* hledger accepts options anywhere on the command line. Instead of - and --
  for pattern negation and separation, use ^ and ^^.
* hledger always keeps differently-priced amounts of the same commodity separate
* hledger calls ledger's "note" field "description"
* hledger doesn't require a space before command-line option values, eg: -f-
* hledger provides "--cost" as a synonym for "--basis"
* 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 period expressions don't support "biweekly", "bimonthly", or "every N days/weeks/..." 
* hledger always shows timelog balances in hours