hledger-0.21: The main command-line interface for the hledger accounting tool.

Safe HaskellNone

Hledger.Cli.Balance

Description

A ledger-compatible balance command.

ledger's balance command is easy to use but not easy to describe precisely. In the examples below we'll use sample.journal, which has the following account tree:

 assets
   bank
     checking
     saving
   cash
 expenses
   food
   supplies
 income
   gifts
   salary
 liabilities
   debts

The balance command shows accounts with their aggregate balances. Subaccounts are displayed indented below their parent. Each balance is the sum of any transactions in that account plus any balances from subaccounts:

 $ hledger -f sample.journal balance
                 $-1  assets
                  $1    bank:saving
                 $-2    cash
                  $2  expenses
                  $1    food
                  $1    supplies
                 $-2  income
                 $-1    gifts
                 $-1    salary
                  $1  liabilities:debts

Usually, the non-interesting accounts are elided or omitted. Above, checking is omitted because it has no subaccounts and a zero balance. bank is elided because it has only a single displayed subaccount (saving) and it would be showing the same balance as that ($1). Ditto for liabilities. We will return to this in a moment.

The --depth argument can be used to limit the depth of the balance report. So, to see just the top level accounts:

$ hledger -f sample.journal balance --depth 1
                 $-1  assets
                  $2  expenses
                 $-2  income
                  $1  liabilities

This time liabilities has no displayed subaccounts (due to --depth) and is not elided.

With one or more account pattern arguments, the balance command shows accounts whose name matches one of the patterns, plus their parents (elided) and subaccounts. So with the pattern o we get:

 $ hledger -f sample.journal balance o
                  $1  expenses:food
                 $-2  income
                 $-1    gifts
                 $-1    salary
--------------------
                 $-1

The o pattern matched food and income, so they are shown. Unmatched parents of matched accounts are also shown (elided) for context (expenses).

Also, the balance report shows the total of all displayed accounts, when that is non-zero. Here, it is displayed because the accounts shown add up to $-1.

Also, non-interesting accounts may be elided. Here's an imperfect description of the ledger balance command's eliding behaviour: "Interesting" accounts are displayed on their own line. An account less deep than the report's max depth, with just one interesting subaccount, and the same balance as the subaccount, is non-interesting, and prefixed to the subaccount's line, unless (hledger's) --no-elide is in effect. An account with a zero inclusive balance and less than two interesting subaccounts is not displayed at all, unless --empty is in effect.

Synopsis

Documentation

balance :: CliOpts -> Journal -> IO ()Source

Print a balance report.

accountsReportAsText :: ReportOpts -> AccountsReport -> [String]Source

Render a balance report as plain text suitable for console output.