hledger-lib-0.22: Core data types, parsers and utilities for the hledger accounting tool.

Safe Haskell | None

Hledger.Reports

Contents

- Report options
- Entries report
- Postings report
- Transactions report
- Balance reports
- Other reports
- Tests

Description

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.

Synopsis

- data ReportOpts = ReportOpts {
  - 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
  }
- data BalanceType
  - = PeriodBalance
  - | CumulativeBalance
  - | HistoricalBalance
- type DisplayExp = String
- type FormatStr = String
- defreportopts :: ReportOpts
- dateSpanFromOpts :: Day -> ReportOpts -> DateSpan
- intervalFromOpts :: ReportOpts -> Interval
- clearedValueFromOpts :: ReportOpts -> Maybe Bool
- whichDateFromOpts :: ReportOpts -> WhichDate
- journalSelectingAmountFromOpts :: ReportOpts -> Journal -> Journal
- queryFromOpts :: Day -> ReportOpts -> Query
- queryOptsFromOpts :: Day -> ReportOpts -> [QueryOpt]
- reportSpans :: ReportOpts -> Query -> Journal -> (DateSpan, [DateSpan])
- type EntriesReport = [EntriesReportItem]
- type EntriesReportItem = Transaction
- entriesReport :: ReportOpts -> Query -> Journal -> EntriesReport
- type PostingsReport = (String, [PostingsReportItem])
- type PostingsReportItem = (Maybe Day, Maybe String, Posting, MixedAmount)
- postingsReport :: ReportOpts -> Query -> Journal -> PostingsReport
- mkpostingsReportItem :: Bool -> Bool -> WhichDate -> Posting -> MixedAmount -> PostingsReportItem
- type TransactionsReport = (String, [TransactionsReportItem])
- 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
- accountTransactionsReport :: ReportOpts -> Journal -> Query -> Query -> TransactionsReport
- type BalanceReport = ([BalanceReportItem], MixedAmount)
- type BalanceReportItem = (AccountName, AccountName, Int, MixedAmount)
- balanceReport :: ReportOpts -> Query -> Journal -> BalanceReport
- newtype MultiBalanceReport = MultiBalanceReport ([DateSpan], [MultiBalanceReportItem], [MixedAmount])
- type MultiBalanceReportItem = (RenderableAccountName, [MixedAmount])
- type RenderableAccountName = (AccountName, AccountName, Int)
- periodBalanceReport :: ReportOpts -> Query -> Journal -> MultiBalanceReport
- cumulativeOrHistoricalBalanceReport :: ReportOpts -> Query -> Journal -> MultiBalanceReport
- accountBalanceHistory :: ReportOpts -> Journal -> Account -> [(Day, MixedAmount)]
- tests_Hledger_Reports :: Test

# Report options

data ReportOpts Source

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 Source

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 Source

type FormatStr = String Source

defreportopts :: ReportOpts Source

dateSpanFromOpts :: Day -> ReportOpts -> DateSpan Source

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 Source

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

clearedValueFromOpts :: ReportOpts -> Maybe Bool Source

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

whichDateFromOpts :: ReportOpts -> WhichDate Source

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

journalSelectingAmountFromOpts :: ReportOpts -> Journal -> Journal Source

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

queryFromOpts :: Day -> ReportOpts -> Query Source

Convert report options and arguments to a query.

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

Convert report options and arguments to query options.

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

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]Source

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 Source

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

Select transactions for an entries report.

# Postings report

type PostingsReport = (String, [PostingsReportItem])Source

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)Source

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

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 Source

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])Source

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)Source

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

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

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

transactionsReportByCommodity :: TransactionsReport -> [TransactionsReport]Source

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

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 Source

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)Source

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)Source

- 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 Source

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

newtype MultiBalanceReport Source

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])Source

- 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)Source

- 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 Source

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 Source

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)]Source

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 Source