Documentation

Standard options for customising report filtering and output. Most of these correspond to standard hledger command-line options or query arguments, but not all. Some are used only by certain commands, as noted below.

Lenses for ReportOpts.

Special lenses for ReportOpts which also update the Query and QueryOpts in ReportSpec. Note that these are not true lenses, as they have a further restriction on the functor. This will work as a normal lens for all common uses, but since they don't obey the lens laws for some fancy cases, they may fail in some exotic circumstances.

Note that setEither/overEither should only be necessary with querystring and reportOpts: the other lenses should never fail.

Examples:

>>> import Lens.Micro (set)
>>> _rsQuery <$> setEither querystring ["assets"] defreportspec
Right (Acct (RegexpCI "assets"))
>>> _rsQuery <$> setEither querystring ["(assets"] defreportspec
Left "This regular expression is invalid or unsupported, please correct it:\n(assets"
>>> _rsQuery $ set querystring ["assets"] defreportspec
Acct (RegexpCI "assets")
>>> _rsQuery $ set period (MonthPeriod 2021 08) defreportspec
Date DateSpan 2021-08

XXX testing error output isn't working since adding color to it: > import System.Environment > setEnv NO_COLOR "1" >> return (_rsQuery $ set querystring ["(assets"] defreportspec) *** Exception: Error: Updating ReportSpec failed: try using overEither instead of over or setEither instead of set

A fully-determined set of report parameters (report options with all partial values made total, eg the begin and end dates are known, avoiding date/regex errors; plus the reporting date), and the query successfully calculated from them.

If you change the report options or date in one of these, you should use reportOptsToSpec to regenerate the whole thing, avoiding inconsistency.

Apply a function over a lens, but report on failure.

Set a field using a lens, but report on failure.

What to calculate for each cell in a balance report. "Balance report types -> Calculation type" in the hledger manual.

How to accumulate calculated values across periods (columns) in a balance report. "Balance report types -> Accumulation type" in the hledger manual.

Should accounts be displayed: in the command's default style, hierarchically, or as a flat list ?

What kind of value conversion should be done on amounts ? CLI: --value=then|end|now|DATE[,COMM]

Generate a ReportOpts from raw command-line input, given a day and whether to use ANSI colour/styles in standard output. This will fail with a usage error if it is passed - an invalid --format argument, - an invalid --value argument, - if --valuechange is called with a valuation type other than -V/--value=end. - an invalid --pretty argument,

Set the default ConversionOp.

Generate a ReportSpec from a set of ReportOpts on a given day.

Update the ReportOpts and the fields derived from it in a ReportSpec, or return an error message if there is a problem such as missing or unparseable options data. This is the safe way to change a ReportSpec, ensuring that all fields (_rsQuery, _rsReportOpts, querystring_, etc.) are in sync.

Like updateReportSpec, but takes a ReportOpts-modifying function.

Generate a ReportSpec from RawOpts and a provided day, or return an error string if there are regular expression errors.

Legacy-compatible convenience aliases for accountlistmode_.

Add/remove this status from the status list. Used by hledger-ui.

Reduce a list of statuses to just one of each status, and if all statuses are present return the empty list.

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

Convert a Journal's amounts to cost and/or to value (see journalApplyValuationFromOpts), and filter by the ReportSpec Query.

We make sure to first filter by amt: and cur: terms, then value the Journal, then filter by the remaining terms.

Like journalValueAndFilterPostings, but takes a PriceOracle as an argument.

Convert this journal's postings' amounts to cost and/or to value, if specified by options (-B--cost-V-X--value etc.). Strip prices if not needed. This should be the main stop for performing costing and valuation. The exception is whenever you need to perform valuation _after_ summing up amounts, as in a historical balance report with --value=end. valuationAfterSum will check for this condition.

Like journalApplyValuationFromOpts, but takes PriceOracle as an argument.

Select the Account valuation functions required for performing valuation after summing amounts. Used in MultiBalanceReport to value historical and similar reports.

If the ReportOpts specify that we are performing valuation after summing amounts, return Just of the commodity symbol we're converting to, Just Nothing for the default, and otherwise return Nothing. Used for example with historical reports with --value=end.

Get the report interval, if any, specified by the last of -p/--period, -D--daily, -W--weekly, -M/--monthly etc. options. An interval from --period counts only if it is explicitly defined.

Convert report options to a query, ignoring any non-flag command line arguments.

Select the Transaction date accessor based on --date2.

Select the Posting date accessor based on --date2.

The effective report span is the start and end dates specified by options or queries, or otherwise the earliest and latest transaction or posting dates in the journal. If no dates are specified by options/queries and the journal is empty, returns the null date span. Also return the intervals if they are requested.

Like reportSpan, but uses both primary and secondary dates when calculating the span.

Make a name for the given period in a multiperiod report, given the type of balance being reported and the full set of report periods. This will be used as a column heading (or row heading, in a register summary report). We try to pick a useful name as follows:

• ending-balance reports: the period's end date
• balance change reports where the periods are months and all in the same year: the short month name in the current locale
• all other balance change reports: a description of the datespan, abbreviated to compact form if possible (see showDateSpan).