hledger-1.3: Command-line interface for the hledger accounting tool

Safe Haskell | None
Language | Haskell2010

Hledger.Cli.Balance

Description

A ledger-compatible `balance` command, with additional support for multi-column reports.

Here is a description/specification for the balance command. See also Hledger.Reports -> "Balance reports".

Basic balance report

With no report interval (`--monthly` etc.), hledger's balance command emulates ledger's, showing accounts indented according to hierarchy, along with their total amount posted (including subaccounts).

Here's an example. With `examples/sample.journal`, which defines the following account tree:

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

the basic `balance` command gives this output:

     $ 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
    --------------------
                       0

Subaccounts are displayed indented below their parent. Only the account leaf name (the final part) is shown. (With `--flat`, account names are shown in full and unindented.)

Each account's "balance" is the sum of postings in that account and any subaccounts during the report period. When the report period includes all transactions, this is equivalent to the account's current balance.

The overall total of the highest-level displayed accounts is shown below the line. (The `--no-total/-N` flag prevents this.)

Eliding and omitting

Accounts which have a zero balance, and no non-zero subaccount balances, are normally omitted from the report. (The `--empty/-E` flag forces such accounts to be displayed.) Eg, above `checking` is omitted because it has a zero balance and no subaccounts.

Accounts which have a single subaccount also being displayed, with the same balance, are normally elided into the subaccount's line. (The `--no-elide` flag prevents this.) Eg, above `bank` is elided to `bank:saving` because it has only a single displayed subaccount (`saving`) and their balance is the same ($1). Similarly, `liabilities` is elided to `liabilities:debts`.

Date limiting

The default report period is that of the whole journal, including all known transactions. The `--begin/-b`, `--end/-e`, `--period/-p` options or `date:`/`date2:` patterns can be used to report only on transactions before and/or after specified dates.

Depth limiting

The `--depth` option can be used to limit the depth of the balance report. Eg, to see just the top level accounts (still including their subaccount balances):

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

Account limiting

With one or more account pattern arguments, the report is restricted to accounts whose name matches one of the patterns, plus their parents and subaccounts. Eg, adding the pattern `o` to the first example gives:

     $ 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.
- `food`'s parent (`expenses`) is shown even though the pattern didn't match it, to clarify the hierarchy. The usual eliding rules cause it to be elided here.
- `income`'s subaccounts are also shown.

Multi-column balance report

hledger's balance command will show multiple columns when a reporting interval is specified (eg with `--monthly`), one column for each sub-period.

There are three kinds of multi-column balance report, indicated by the heading:

- A "period balance" (or "flow") report (the default) shows the change of account balance in each period, which is equivalent to the sum of postings in each period. Here, checking's balance increased by 10 in Feb:

    Change of balance (flow):

                     Jan   Feb   Mar
    assets:checking   20    10    -5

- A "cumulative balance" report (with `--cumulative`) shows the accumulated ending balance across periods, starting from zero at the report's start date. Here, 30 is the sum of checking postings during Jan and Feb:

    Ending balance (cumulative):

                     Jan   Feb   Mar
    assets:checking   20    30    25

- A "historical balance" report (with `--historical/-H`) also shows ending balances, but it includes the starting balance from any postings before the report start date. Here, 130 is the balance from all checking postings at the end of Feb, including pre-Jan postings which created a starting balance of 100:

    Ending balance (historical):

                     Jan   Feb   Mar
    assets:checking  120   130   125

Eliding and omitting, 2

Here's a (imperfect?) specification for the eliding/omitting behaviour:

- Each account is normally displayed on its 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 `--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.
- Multi-column balance reports show full account names with no eliding (like `--flat`). Accounts (and periods) are omitted as described below.

Which accounts to show in balance reports

By default:

- single-column: accounts with non-zero balance in report period. (With `--flat`: accounts with non-zero balance and postings.)
- periodic: accounts with postings and non-zero period balance in any period
- cumulative: accounts with non-zero cumulative balance in any period
- historical: accounts with non-zero historical balance in any period

With `-E/--empty`:

- single-column: accounts with postings in report period
- periodic: accounts with postings in report period
- cumulative: accounts with postings in report period
- historical: accounts with non-zero starting balance + accounts with postings in report period

Which periods (columns) to show in balance reports

An empty period/column is one where no report account has any postings. A zero period/column is one where no report account has a non-zero period balance.

Currently,

by default:

- single-column: N/A
- periodic: all periods within the overall report period, except for leading and trailing empty periods
- cumulative: all periods within the overall report period, except for leading and trailing empty periods
- historical: all periods within the overall report period, except for leading and trailing empty periods

With `-E/--empty`:

- single-column: N/A
- periodic: all periods within the overall report period
- cumulative: all periods within the overall report period
- historical: all periods within the overall report period

What to show in empty cells

An empty periodic balance report cell is one which has no corresponding postings. An empty cumulative/historical balance report cell is one which has no correponding or prior postings, ie the account doesn't exist yet. Currently, empty cells show 0.

Synopsis

- balancemode :: Mode RawOpts
- balance :: CliOpts -> Journal -> IO ()
- balanceReportAsText :: ReportOpts -> BalanceReport -> String
- balanceReportItemAsText :: ReportOpts -> StringFormat -> BalanceReportItem -> [String]
- multiBalanceReportAsText :: ReportOpts -> MultiBalanceReport -> String
- renderBalanceReportTable :: ReportOpts -> Table String String MixedAmount -> String
- balanceReportAsTable :: ReportOpts -> MultiBalanceReport -> Table String String MixedAmount
- tests_Hledger_Cli_Balance :: Test

# Documentation

balancemode :: Mode RawOpts #

Command line options for this command.

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

The balance command, prints a balance report.

balanceReportAsText :: ReportOpts -> BalanceReport -> String #

Render a single-column balance report as plain text.

balanceReportItemAsText :: ReportOpts -> StringFormat -> BalanceReportItem -> [String] #

Render one balance report line item as plain text suitable for console output (or whatever string format is specified). Note, prices will not be rendered, and differently-priced quantities of the same commodity will appear merged. The output will be one or more lines depending on the format and number of commodities.

multiBalanceReportAsText :: ReportOpts -> MultiBalanceReport -> String #

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

renderBalanceReportTable :: ReportOpts -> Table String String MixedAmount -> String #

Given a table representing a multi-column balance report (for example, made using `balanceReportAsTable`), render it in a format suitable for console output.

balanceReportAsTable :: ReportOpts -> MultiBalanceReport -> Table String String MixedAmount #

Build a `Table` from a multi-column balance report.

tests_Hledger_Cli_Balance :: Test #