Hledger.Reports

Generate several common kinds of report from a journal, as "*Report" - simple intermediate data structures intended to be easily rendered as text, html, json, csv etc. by hledger commands, hamlet templates, javascript, or whatever.

Report options

data ReportOpts

Standard options for customising report filtering and output, corresponding to hledger's command-line options and query language arguments. Used in hledger-lib and above.

Constructors

ReportOpts

Fields

begin_ :: Maybe Day

end_ :: Maybe Day

period_ :: Maybe (Interval, DateSpan)

cleared_ :: Bool

uncleared_ :: Bool

cost_ :: Bool

depth_ :: Maybe Int

display_ :: Maybe DisplayExp

date2_ :: Bool

empty_ :: Bool

no_elide_ :: Bool

real_ :: Bool

balancetype_ :: BalanceType

flat_ :: Bool

drop_ :: Int

no_total_ :: Bool

daily_ :: Bool

weekly_ :: Bool

monthly_ :: Bool

quarterly_ :: Bool

yearly_ :: Bool

format_ :: Maybe FormatStr

related_ :: Bool

average_ :: Bool

query_ :: String

Instances

Data ReportOpts

Show ReportOpts

Typeable ReportOpts

Default ReportOpts

data BalanceType

Which balance is being shown in a multi-column balance report.

Constructors

PeriodBalance

The change of balance in each period.

CumulativeBalance

The accumulated balance at each period's end, starting from zero at the report start date.

HistoricalBalance

The historical balance at each period's end, starting from the account balances at the report start date.

Instances

Eq BalanceType

Data BalanceType

Show BalanceType

Typeable BalanceType

Default BalanceType

type DisplayExp = String

type FormatStr = String

defreportopts :: ReportOpts

dateSpanFromOpts :: Day -> ReportOpts -> DateSpan

Figure out the date span we should report on, based on any beginendperiod options provided. A period option will cause begin and end options to be ignored.

intervalFromOpts :: ReportOpts -> Interval

Figure out the reporting interval, if any, specified by the options. --period overrides --daily overrides --weekly overrides --monthly etc.

clearedValueFromOpts :: ReportOpts -> Maybe Bool

Get a maybe boolean representing the last cleared/uncleared option if any.

whichDateFromOpts :: ReportOpts -> WhichDate

Report which date we will report on based on --date2.

journalSelectingAmountFromOpts :: ReportOpts -> Journal -> Journal

Convert this journal's postings' amounts to the cost basis amounts if specified by options.

queryFromOpts :: Day -> ReportOpts -> Query

Convert report options and arguments to a query.

queryOptsFromOpts :: Day -> ReportOpts -> [QueryOpt]

Convert report options and arguments to query options.

reportSpans :: ReportOpts -> Query -> Journal -> (DateSpan, [DateSpan])

Calculate the overall span and per-period date spans for a report based on command-line options, the parsed search query, and the journal data. If a reporting interval is specified, the report span will be enlarged to include a whole number of report periods. Reports will sometimes trim these spans further when appropriate.

Entries report

type EntriesReport = [EntriesReportItem]

A journal entries report is a list of whole transactions as originally entered in the journal (mostly). This is used by eg hledger's print command and hledger-web's journal entries view.

type EntriesReportItem = Transaction

entriesReport :: ReportOpts -> Query -> Journal -> EntriesReport

Select transactions for an entries report.

Postings report

type PostingsReport = (String, [PostingsReportItem])

A postings report is a list of postings with a running total, a label for the total field, and a little extra transaction info to help with rendering. This is used eg for the register command.

type PostingsReportItem = (Maybe Day, Maybe String, Posting, MixedAmount)

postingsReport :: ReportOpts -> Query -> Journal -> PostingsReport

Select postings from the journal and add running balance and other information to make a postings report. Used by eg hledger's register command.

mkpostingsReportItem :: Bool -> Bool -> WhichDate -> Posting -> MixedAmount -> PostingsReportItem

Generate one postings report line item, containing the posting, the current running balance, and optionally the posting date and/or the transaction description.

Transactions report

type TransactionsReport = (String, [TransactionsReportItem])

A transactions report includes a list of transactions (posting-filtered and unfiltered variants), a running balance, and some other information helpful for rendering a register view (a flag indicating multiple other accounts and a display string describing them) with or without a notion of current account(s). Two kinds of report use this data structure, see journalTransactionsReport and accountTransactionsReport below for detais.

type TransactionsReportItem = (Transaction, Transaction, Bool, String, MixedAmount, MixedAmount)

triDate :: (Transaction, t, t1, t2, t3, t4) -> Day

triBalance :: (t, t1, t2, t3, t4, t5) -> t5

triSimpleBalance :: (t, t1, t2, t3, t4, MixedAmount) -> [Char]

transactionsReportByCommodity :: TransactionsReport -> [TransactionsReport]

journalTransactionsReport :: ReportOpts -> Journal -> Query -> TransactionsReport

Select transactions from the whole journal. This is similar to a postingsReport except with transaction-based report items which are ordered most recent first. This is used by eg hledger-web's journal view.

accountTransactionsReport :: ReportOpts -> Journal -> Query -> Query -> TransactionsReport

Select transactions within one or more current accounts, and make a transactions report relative to those account(s). This means:

1. it shows transactions from the point of view of the current account(s). The transaction amount is the amount posted to the current account(s). The other accounts' names are provided.
2. With no transaction filtering in effect other than a start date, it shows the accurate historical running balance for the current account(s). Otherwise it shows a running total starting at 0.

This is used by eg hledger-web's account register view. Currently, reporting intervals are not supported, and report items are most recent first.

Balance reports

These are used for the various modes of the balance command (see Hledger.Cli.Balance).

type BalanceReport = ([BalanceReportItem], MixedAmount)

A list of account names plus rendering info, along with their balances as of the end of the reporting period, and the grand total. Used for the balance command's single-column mode.

type BalanceReportItem = (AccountName, AccountName, Int, MixedAmount)

• Full account name,
• short account name for display (the leaf name, prefixed by any boring parents immediately above),
• how many steps to indent this account (the 0-based account depth excluding boring parents, or 0 with --flat),
• account balance (including subaccounts (XXX unless --flat)).

balanceReport :: ReportOpts -> Query -> Journal -> BalanceReport

Select accounts, and get their balances at the end of the selected period, and misc. display information, for an accounts report.

newtype MultiBalanceReport

A multi(column) balance report is a list of accounts, each with a list of balances corresponding to the report's column periods. The balances' meaning depends on the type of balance report (see BalanceType and Hledger.Cli.Balance). Also included are the overall total for each period, the date span for each period, and some additional rendering info for the accounts.

• The date span for each report column,
• line items (one per account),
• the final total for each report column.

Constructors

MultiBalanceReport ([DateSpan], [MultiBalanceReportItem], [MixedAmount])

Instances

Show MultiBalanceReport

type MultiBalanceReportItem = (RenderableAccountName, [MixedAmount])

• The account name with rendering hints,
• the account's balance (per-period balance, cumulative ending balance, or historical ending balance) in each of the report's periods.

type RenderableAccountName = (AccountName, AccountName, Int)

• Full account name,
• ledger-style short account name (the leaf name, prefixed by any boring parents immediately above),
• indentation steps to use when rendering a ledger-style account tree (the 0-based depth of this account excluding boring parents; or with --flat, 0)

periodBalanceReport :: ReportOpts -> Query -> Journal -> MultiBalanceReport

Select accounts and get their period balance (change of balance) in each period, plus misc. display information, for a period balance report.

cumulativeOrHistoricalBalanceReport :: ReportOpts -> Query -> Journal -> MultiBalanceReport

Select accounts and get their ending balance in each period, plus account name display information, for a cumulative or historical balance report.

Other reports

accountBalanceHistory :: ReportOpts -> Journal -> Account -> [(Day, MixedAmount)]

Get the historical running inclusive balance of a particular account, from earliest to latest posting date. XXX Accounts should know the Ledger & Journal they came from

Tests

tests_Hledger_Reports :: Test