Hledger.Cli

hledger CLI's main procedure.

Here we will parse the command line, read any config file, and search for hledger-* addon executables in the user's PATH, then choose the appropriate builtin operation or addon operation to run, then run it in the right way, usually reading input data (eg a journal) first.

When making a CLI usable and robust with main command, builtin subcommands, various kinds of addon commands, and config files that add general and command-specific options, while balancing circular dependencies, environment, idioms, legacy, and libraries with their own requirements and limitations: things get crazy, and there is a tradeoff against complexity and bug risk. We try to provide the most intuitive, expressive and robust CLI that's feasible while keeping the CLI processing below sufficiently comprehensible, troubleshootable, and tested. It's an ongoing quest. See also: Hledger.Cli.CliOptions, cli.test, addons.test, --debug and --debug=8.

Probably the biggest source of complexity here is that cmdargs can't parse a command line containing undeclared flags, but this arises often with our addon commands and builtin/custom commands which haven't implemented all options, so we have to work hard to work around this. https://github.com/ndmitchell/cmdargs/issues/36 is the wishlist issue; implementing that would simplify hledger's CLI processing a lot.

The overall cmdargs mode describing hledger's command-line options and subcommands. The names of known addons are provided so they too can be recognised as commands.

A helper for addons/scripts: this parses hledger CliOpts from these command line arguments and add-on command names, roughly how hledger main does. If option parsing/validating fails, it exits the program with usageError. Unlike main, this does not read extra args from a config file or search for addons; to do those things, mimic the code in main for now.

Returns width of a character in a monospace font: 0 for a combining character, 1 for a regular character, 2 for an East Asian wide character. Ambiguous characters are treated as width 1.

The trace function outputs the trace message given as its first argument, before returning the second argument as its result.

For example, this returns the value of f x and outputs the message to stderr. Depending on your terminal (settings), they may or may not be mixed.

>>> let x = 123; f = show>>> trace ("calling f with x = " ++ show x) (f x)calling f with x = 123"123"

The trace function should only be used for debugging, or for monitoring execution. The function is not referentially transparent: its type indicates that it is a pure function but it has the side effect of outputting the trace message.

The traceIO function outputs the trace message from the IO monad. This sequences the output with respect to other IO actions.

Like traceShow but returns the shown value instead of a third value.

>>> traceShowId (1+2+3, "hello" ++ "world")(6,"helloworld")(6,"helloworld")

Construct an 'Account" from an account name and balances. Other fields are left blank.

Derive 1. an account tree and 2. each account's total exclusive and inclusive changes associated with dates from a list of postings and a function for associating a date to each posting (usually representing the start dates of report subperiods). This is the core of the balance command (and of *ledger). The accounts are returned as a tree.

Add extra info for this account derived from the Journal's account directives, if any (comment, tags, declaration order..).

Convert a list of account names to a tree of Account objects, with just the account names filled in and an empty balance. A single root account with the given name is added.

Convert a list of account names to a tree of Account objects, with just the account names filled in. Each account is given the same supplied balance. A single root account with the given name is added.

Derive 1. an account tree and 2. each account's total exclusive and inclusive changes associated with dates from a list of postings and a function for associating a date to each posting (usually representing the start dates of report subperiods). This is the core of the balance command (and of *ledger). The accounts are returned as a list in flattened tree order, and also reference each other as a tree. (The first account is the root of the tree.)

List the accounts at each level of the account tree.

Is the predicate true on any of this account or its subaccounts ?

Remove all subaccounts below a certain depth.

Remove subaccounts below the specified depth, aggregating their balance at the depth limit (accounts at the depth limit will have any sub-balances merged into their exclusive balance). If the depth is Nothing, return the original accounts

Filter an account tree (to a list).

Flatten an account tree into a list, which is sometimes convenient. Note since accounts link to their parents/subs, the tree's structure remains intact and can still be used. It's a tree/list!

Search an account list by name.

Map a (non-tree-structure-modifying) function over this and sub accounts.

Apply a function to all PeriodData within this and sub accounts.

Merge two account trees and their subaccounts.

This assumes that the top-level Accounts have the same name.

Get this account's parent accounts, from the nearest up to the root.

Remove all leaf accounts and subtrees matching a predicate.

Sort account names by the order in which they were declared in the journal, at each level of the account tree (ie within each group of siblings). Undeclared accounts are sorted last and alphabetically. This is hledger's default sort for reports organised by account. The account list is converted to a tree temporarily, adding any missing parents; these can be kept (suitable for a tree-mode report) or removed (suitable for a flat-mode report).

Sort each group of siblings in an account tree by declaration order, then account name. So each group will contain first the declared accounts, in the same order as their account directives were parsed, and then the undeclared accounts, sorted by account name.

Sort each group of siblings in an account tree by projecting through a provided function.

Recalculate all the subaccount-inclusive balances in this tree.

Rewrite an account name using all matching aliases from the given list, in sequence. Each alias sees the result of applying the previous aliases. Or, return any error arising from a bad regular expression in the aliases.

Memoising version of accountNameApplyAliases, maybe overkill.

Remove some number of account name components from the front of the account name. If the special "unbudgeted" top-level account is present, it is preserved and dropping affects the rest of the account name.

Try to guess an account's type from its name, matching common English top-level account names.

Like accountNameInferType, but exclude the provided types from the guesses. Used eg to prevent "equity:conversion" being inferred as Conversion when a different account has been declared with that type.

The level (depth) of an account name.

>>> accountNameLevel ""  -- special case0>>> accountNameLevel "assets"1>>> accountNameLevel "assets:cash"2

Convert an account name to a regular expression matching it but not its subaccounts.

Convert an account name to a regular expression matching it but not its subaccounts, case insensitively.

Convert an account name to a regular expression matching it and its subaccounts.

Convert an account name to a regular expression matching it and its subaccounts, case insensitively.

Convert a list of account names to a tree, efficiently.

Truncate all account name components but the last to two characters.

Regular expressions matching common English top-level account names, used as a fallback when account types are not declared.

Clip an account name to a given DepthSpec, first checking whether it matches any of the regular expressions controlling depth. If so, clip to the depth of the most specific of those matches, i.e. the one which starts matching the latest as you progress up the parents of the account. Otherwise clip to the flat depth provided, or return the full name if Nothing.

As clipAccountName, but return ... if asked to clip to depth 0.

Join account names into one. If any of them has () or [] posting type indicators, these (the first type encountered) will also be applied to the resulting account name.

Elide an account name to fit in the specified width. From the ledger 2.6 news:

  What Ledger now does is that if an account name is too long, it will
  start abbreviating the first parts of the account name down to two
  letters in length.  If this results in a string that is still too
  long, the front will be elided -- not the end.  For example:

    Expenses:Cash           ; OK, not too long
    Ex:Wednesday:Cash       ; Expenses was abbreviated to fit
    Ex:We:Afternoon:Cash    ; Expenses and Wednesday abbreviated
    ; Expenses:Wednesday:Afternoon:Lunch:Snack:Candy:Chocolate:Cash
    ..:Af:Lu:Sn:Ca:Ch:Cash  ; Abbreviated and elided!

Escape an AccountName for use within a regular expression. >>> putStr . T.unpack $ escapeName "First?!#$*?$(*) !^#*? %)*!#" First?!#$*?$\* !^#*? %)*!#

"a:b:c" -> ["a","a:b","a:b:c"]

Sorted unique account names implied by these account names, ie these plus all their parent accounts up to the root. Eg: ["a:b:c","d:e"] -> ["a","a:b","a:b:c","d","d:e"]

Calculate the depth to which an account name should be clipped for a given DepthSpec.

First checking whether the account name matches any of the regular expressions controlling depth. If so, clip to the depth of the most specific of those matches, i.e. the one which starts matching the latest as you progress up the parents of the account. Otherwise clip to the flat depth provided, or return the full name if Nothing.

Is the first account a parent or other ancestor of (and not the same as) the second ?

Prefix one account name to another, preserving posting type indicators like concatAccountNames.

From a list of account names, select those which are direct subaccounts of the given account name.

"a:b:c" -> "a"

"a:b:c","d:e"

-> ["a","d"]

A top-level account prefixed to some accounts in budget reports. Defined here so it can be ignored by accountNameDrop.

Convert a amount to its total cost in another commodity, using its attached cost amount if it has one. Notes:

• cost amounts must be MixedAmounts with exactly one component Amount (or there will be a runtime error XXX)

• cost amounts should be positive in the Journal (though this is currently not enforced)

How many decimal digits will be displayed for this amount ?

How many internal decimal digits are stored for this amount ?

Is this Amount (and its total cost, if it has one) exactly zero, ignoring its display precision ?

Do this Amount and (and its total cost, if it has one) appear to be zero when rendered with its display precision ? The display precision should usually have a specific value here; if unset, it will be treated like NaturalPrecision.

Increase an amount's display precision, if needed, to enough decimal places to show it exactly (showing all significant decimal digits, without trailing zeros). If the amount's display precision is unset, it will be treated as precision 0.

We often want to display "infinite decimal" amounts rounded to some readable number of digits, while still displaying amounts with a large but "non infinite" number of decimal digits (eg 10 or 100 or 200 digits) in full. This helper is like amountSetFullPrecision, but with some refinements:

1. A maximum display precision can be specified, setting a hard upper limit.

2. If no limit is specified, and the internal precision is the maximum (255), indicating an infinite decimal, display precision is set to a smaller default (8).

This function always sets an explicit display precision (ie, Precision n).

Set an amount's display precision.

Ensure an amount's display precision is at most the given maximum precision. Always sets an explicit Precision.

Ensure an amount's display precision is at least the given minimum precision. Always sets an explicit Precision.

Strip all costs from an Amount

Set this amount style's rounding strategy when it is being applied to amounts.

Set these amount styles' rounding strategy when they are being applied to amounts.

Reset this amount's display style to the default.

Convert an amount to the specified commodity, ignoring and discarding any costs and assuming an exchange rate of 1.

Get a mixed amount's component amounts, with some cleanups. The following descriptions are old and possibly wrong:

• amounts in the same commodity are combined unless they have different costs or total costs

• multiple zero amounts, all with the same non-null commodity, are replaced by just the last of them, preserving the commodity and amount style (all but the last zero amount are discarded)

• multiple zero amounts with multiple commodities, or no commodities, are replaced by one commodity-less zero amount

• an empty amount list is replaced by one commodity-less zero amount

• the special "missing" mixed amount remains unchanged

Get a mixed amount's component amounts, with some cleanups. This is a new version of amounts, with updated descriptions and optimised for print to show commodityful zeros.

• If it contains the "missing amount" marker, only that is returned (discarding any additional amounts).

• Or if it contains any non-zero amounts, only those are returned (discarding any zeroes).

• Or if it contains any zero amounts (possibly more than one, possibly in different commodities), all of those are returned.

• Otherwise the null amount is returned.

Get a mixed amount's component amounts without normalising zero and missing amounts. This is used for JSON serialisation, so the order is important. In particular, we want the Amounts given in the order of the MixedAmountKeys, i.e. lexicographically first by commodity, then by cost commodity, then by unit cost from most negative to most positive.

Default amount style

Calculate the average of some mixed amounts.

Given a list of amounts, in parse order (roughly speaking; see journalStyleInfluencingAmounts), build a map from their commodity names to standard commodity display formats. Can return an error message eg if inconsistent number formats are found.

Though, these amounts may have come from multiple files, so we shouldn't assume they use consistent number formats. Currently we don't enforce that even within a single file, and this function never reports an error.

Colour version. For a negative amount, adds ANSI codes to change the colour, currently to hard-coded red.

cshowAmount = wbUnpack . showAmountB def{displayColour=True}

Display amounts without colour, and with various other defaults.

The fallback display precision used when showing amounts representing an infinite decimal.

Divide an amount's quantity (and total cost, if any) by some number.

Divide a mixed amount's quantities (and total costs, if any) by a constant.

Filter a mixed amount's component amounts by a predicate.

Return an unnormalised MixedAmount containing just the amounts in the requested commodity from the original mixed amount.

The result will contain at least one Amount of the requested commodity, even if the original mixed amount did not (with quantity zero in that case, and this would be discarded when the mixed amount is next normalised).

The result can contain more than one Amount of the requested commodity, eg because there were several with different costs, or simply because the original mixed amount was was unnormalised.

Like defaultFmt but show zero amounts with commodity symbol and styling, like non-zero amounts.

Get an amount and its attached cost amount if any. Returns one or two amounts.

Invert an amount (replace its quantity q with 1/q). The amount's transacted price, if any, is not changed. An amount with zero quantity is left unchanged.

Does this MixedAmount include the "missing amount" marker ? Note: currently does not test for equality with missingmixedamt, instead it looks for missingamt among the Amounts. missingamt should always be alone, but detect it even if not.

Is this amount negative ? The cost is ignored.

Is this mixed amount negative, if we can tell that unambiguously? Ie when normalised, are all individual commodity amounts negative ?

Add an Amount to a MixedAmount, normalising the result. Amounts with different costs are kept separate.

Add a collection of Amounts to a MixedAmount, normalising the result. Amounts with different costs are kept separate.

Get this mixed amount's commodities as a set. Returns an empty set if there are no amounts.

Is this mixed amount non-zero, ignoring its display precision?

A convenient alias for not . mixedAmountIsZero.

Is this mixed amount exactly zero, ignoring its display precision?

A convenient alias for mixedAmountIsZero.

Subtract a MixedAmount from another. Amounts with different costs are kept separate.

Negate mixed amount's quantities (and total costs, if any).

Sum two MixedAmount, keeping the cost of the first if any. Amounts with different costs are kept separate (since 2021).

Sum a collection of MixedAmounts. Amounts with different costs are kept separate.

A (slightly more) machine-readable amount format; like oneLineNoCostFmt but don't show digit group marks.

Apply a transform to a mixed amount's component Amounts.

A special amount used as a marker, meaning "no explicit amount provided here, infer it when needed". It is nullamt with commodity symbol AUTO.

A special mixed amount used as a marker, meaning "no explicit amount provided here, infer it when needed".

Convert amounts in various commodities into a mixed amount.

Create a MixedAmount from a single Amount.

Convert all component amounts to cost where possible (see amountCost).

Is this mixed amount exactly zero, ignoring its display precision? See amountIsZero.

Does this mixed amount appear to be zero when rendered with its display precision? See amountLooksZero.

In each component amount, increase the display precision sufficiently to render it exactly (showing all significant decimal digits).

In each component amount, increase the display precision sufficiently to render it exactly if possible, but not more than the given max precision, and if no max precision is given and the amount has infinite decimals, limit display precision to a hard-coded smaller number (8). See amountSetFullPrecisionUpTo.

Set the display precision in the amount's commodities.

In each component amount, ensure the display precision is at most the given value. Makes all amounts have an explicit Precision.

In each component amount, ensure the display precision is at least the given value. Makes all amounts have an explicit Precision.

Remove all costs from a MixedAmount.

Reset each individual amount's display style to the default.

Multiply an amount's quantity (and its total cost, if it has one) by a constant.

Multiply a mixed amount's quantities (and total costs, if any) by a constant.

Like defaultFmt but don't show costs or cost basis.

The empty simple amount - a zero with no commodity symbol or cost and the default amount display style.

The empty mixed amount.

Like defaultFmt but display all amounts on one line.

Like noCostFmt but display all amounts on one line.

Set (or clear) an amount's display decimal point.

Set an amount's internal decimal precision as well as its display precision. This rounds or pads its Decimal quantity to the specified number of decimal places. Rounding is done with Data.Decimal's default roundTo function: "If the value ends in 5 then it is rounded to the nearest even value (Banker's Rounding)".

Render an amount using its display style and the default amount format. Zero-equivalent amounts are shown as just "0". The special "missing" amount is shown as the empty string.

Render an amount using its display style and the given amount format, as a builder for efficiency. (This can be converted to a Text with wbToText or to a String with wbUnpack). The special "missing" amount is displayed as the empty string.

Show an amount's cost basis as Ledger-style lot syntax: {LOTCOST} LOTDATE.

Get a string representation of an amount for debugging, appropriate to the current debug level. 9 shows maximum detail.

Like showAmount but uses the given amount format.

Like showAmount, but show a zero amount's commodity if it has one.

showAmountWithZeroCommodity = wbUnpack . showAmountB defaultFmt{displayZeryCommodity=True}

Get the string representation of an amount, without any @ cost.

showAmountWithoutCost = wbUnpack . showAmountB noCostFmt

Show space-containing commodity symbols quoted, as they are in a journal.

Render a mixed amount using its amount display styles and the default amount format, after normalising it (to at most one amount in each of its commodities). See showMixedAmountB for special cases.

Render a mixed amount using its amount display styles and the given amount format, as a builder for efficiency. (This can be converted to a Text with wbToText or to a String with wbUnpack).

Warning: this (and its showMixedAmount aliases above) basically assumes amounts have no costs. It can show misleading costs or not show costs which are there.

If a maximum width is given then:

• If displayed on one line, it will display as many Amounts as can fit in the given width, and further Amounts will be elided. There will always be at least one amount displayed, even if this will exceed the requested maximum width.

• If displayed on multiple lines, any Amounts longer than the maximum width will be elided.

Zero-equivalent amounts are shown as just "0".

The special "missing" amount is shown as the empty string (?).

Get an unambiguous string representation of a mixed amount for debugging.

Like showMixedAmountOneLineWithoutCost, but show at most the given width, with an elision indicator if there are more. With a True argument, adds ANSI codes to show negative amounts in red. See showMixedAmountB for special cases.

Helper for showMixedAmountB (and postingAsLines, ...) to show a list of Amounts on multiple lines. This returns the list of WideBuilders: one for each Amount, and padded/elided to the appropriate width. This does not honour displayOneLine; all amounts will be displayed as if displayOneLine were False.

Like showMixedAmountLinesB but also returns the amounts associated with each text builder.

Get the one-line string representation of a mixed amount (also showing any costs). See showMixedAmountB for special cases.

Get the one-line string representation of a mixed amount, but without any @ costs. With a True argument, adds ANSI codes to show negative amounts in red. See showMixedAmountB for special cases.

Like showMixedAmount but uses the given amount format. See showMixedAmountB for special cases.

Like showMixedAmount, but zero amounts are shown with their commodity if they have one. See showMixedAmountB for special cases.

Get the string representation of a mixed amount, without showing any costs. With a True argument, adds ANSI codes to show negative amounts in red. See showMixedAmountB for special cases.

Given a map of standard commodity display styles, find and apply the appropriate style to each individual amount.

Calculate the sum and average of some mixed amounts.

Unify a MixedAmount to a single commodity value if possible. This consolidates amounts of the same commodity and discards zero amounts; but this one insists on simplifying to a single commodity, and will return Nothing if this is not possible.

Set (or clear) an amount's display decimal point, flipped.

setAmountInternalPrecision with arguments flipped.

Set an amount's display precision, flipped.

Apply an operation to both MixedAmount in an BalanceData.

Merge two BalanceData, using the given operation to combine their amounts.

Balance this isolated transaction, ensuring that its postings (and its balanced virtual postings) sum to 0, by inferring a missing amount or conversion price(s) if needed. Or if balancing is not possible, because the amounts don't sum to 0 or because there's more than one missing amount, return an error message.

Note this is not as accurate as balanceTransactionInJournal, which considers the whole journal when calculating balance assignments and balance assertions.

Helper used by balanceSingleTransaction and balanceTransactionWithBalanceAssignmentAndCheckAssertionsB; use one of those instead. It also returns a list of accounts and amounts that were inferred.

Legacy form of transactionCheckBalanced.

Infer any missing amounts and/or conversion costs (as needed to balance transactions and satisfy balance assignments); and check that all transactions are balanced; and (optional) check that all balance assertions pass. Or, return an error message (just the first error encountered).

Assumes journalStyleAmounts has been called, since amount styles affect transaction balancing.

This does multiple things at once because amount inferring, balance assignments, balance assertions and posting dates are interdependent.

Verify that any assertions in this transaction hold when included in the larger journal.

Look for a currency symbol corresponding to this ISO 4217 currency code.

>>> currencyCodeToSymbol "CZK"  -- Just "Kč"Just "K\269"

Look for a ISO 4217 currency code corresponding to this currency symbol.

>>> currencySymbolToCode ""Nothing>>> currencySymbolToCode "$"Just "USD"

Advance to the nth occurrence of the given weekday, on or after the given date. Can call error.

Count the days in a DateSpan, or if it is open-ended return Nothing.

Calculate the minimal DateSpan containing all of the given Days (in the usual exclusive-end-date sense: beginning on the earliest, and ending on the day after the latest).

An exact datespan of zero length, that matches no date.

Convert a SmartDate to a specific date using the provided reference date. This date will be exact or flexible depending on whether the day was specified exactly. (Missing least-significant parts produces a flex date.)

Examples:

>>> :set -XOverloadedStrings>>> let t = fixSmartDateStr (fromGregorian 2008 11 26)>>> t "0000-01-01""0000-01-01">>> t "1999-12-02""1999-12-02">>> t "1999.12.02""1999-12-02">>> t "1999/3/2""1999-03-02">>> t "19990302""1999-03-02">>> t "2008/2""2008-02-01">>> t "0020/2""0020-02-01">>> t "1000""1000-01-01">>> t "4/2""2008-04-02">>> t "2""2008-11-02">>> t "January""2008-01-01">>> t "feb""2008-02-01">>> t "today""2008-11-26">>> t "yesterday""2008-11-25">>> t "tomorrow""2008-11-27">>> t "this day""2008-11-26">>> t "last day""2008-11-25">>> t "next day""2008-11-27">>> t "this week"  -- last monday"2008-11-24">>> t "last week"  -- previous monday"2008-11-17">>> t "next week"  -- next monday"2008-12-01">>> t "this month""2008-11-01">>> t "last month""2008-10-01">>> t "next month""2008-12-01">>> t "this quarter""2008-10-01">>> t "last quarter""2008-07-01">>> t "next quarter""2009-01-01">>> t "this year""2008-01-01">>> t "last year""2007-01-01">>> t "next year""2009-01-01"

refdate is Wednesday, 2008-11-26 >>> t "last wednesday" "2008-11-19" >>> t "this wednesday" "2008-12-03" >>> t "next wednesday" "2008-12-03" >>> t "last january" "2008-01-01" >>> t "this january" "2009-01-01" >>> t "next january" "2009-01-01" >>> t "last november" "2007-11-01" >>> t "this november" "2009-11-01" >>> t "next november" "2009-11-01"

>>> t "in 5 days""2008-12-01">>> t "in 7 months""2009-06-01">>> t "in -2 weeks""2008-11-10">>> t "1 quarter ago""2008-07-01">>> t "1 week ahead""2008-12-01"

Convert a smart date string to an explicit yyyy/mm/dd string using the provided reference date, or raise an error.

A safe version of fixSmartDateStr.

Get the current local date.

Get the current local month number.

Get the current local year.

Group elements based on where they fall in a list of DateSpans without gaps. The precondition is not checked.

Is this an empty span, ie closed with the end date on or before the start date ?

Select the DateSpan containing a given Day, if any, from a given list of DateSpans.

If the DateSpans are non-overlapping, this returns the unique containing DateSpan, if it exists. If the DateSpans are overlapping, it will return the containing DateSpan with the latest start date, and then latest end date.

Find the next occurrence of some nth weekday of a month, on or after the given date d.

>>> let wed22nd = fromGregorian 2017 11 22>>> nextNthWeekdayOfMonth 3 3 wed22nd  -- next third wednesday2017-12-20>>> nextNthWeekdayOfMonth 4 3 wed22nd  -- next fourth wednesday2017-11-22>>> nextNthWeekdayOfMonth 5 3 wed22nd  -- next fifth wednesday2017-11-29

Find the next occurrence of the specified month and day of month, on or after the given date. The month should be 1-12 and the day of month should be 1-31, or an error will be raised.

>>> let wed22nd = fromGregorian 2017 11 22>>> nextmonthandday 11 21 wed22nd2018-11-21>>> nextmonthandday 11 22 wed22nd2017-11-22>>> nextmonthandday 11 23 wed22nd2017-11-23

Find the next occurrence of the specified day of month, on or after the given date. The day of month should be 1-31, or an error will be raised.

>>> let wed22nd = fromGregorian 2017 11 22>>> nextnthdayofmonth 21 wed22nd2017-12-21>>> nextnthdayofmonth 22 wed22nd2017-11-22>>> nextnthdayofmonth 23 wed22nd2017-11-23

For given date d find week-long interval that starts on nth day of week and covers it.

Examples: 2017-11-22 is Wed. Week-long intervals that cover it and start on Mon, Tue or Wed will start in the same week. However intervals that start on Thu or Fri should start in prev week: >>> let wed22nd = fromGregorian 2017 11 22 >>> nthdayofweekcontaining 1 wed22nd 2017-11-20 >>> nthdayofweekcontaining 2 wed22nd 2017-11-21 >>> nthdayofweekcontaining 3 wed22nd 2017-11-22 >>> nthdayofweekcontaining 4 wed22nd 2017-11-16 >>> nthdayofweekcontaining 5 wed22nd 2017-11-17

Parse a period expression to an Interval and overall DateSpan using the provided reference date, or return a parse error.

Like parsePeriodExpr, but call error' on failure.

A simple date parsing helper: parses these YMD date string formats: `YYYY-MM-DD`, `YYYYMMDD`, YYYY.MM.DD or YYYYMMDD, where the month and day each have two digits and the year has one or more.

This is different from the Smart Dates of the CLI and period expressions ("smartdate", below) and not quite the same as the Simple Dates of the journal ("datep", in Hledger.Read.Common). It's mainly for internal or interactive use, eg when debugging - but currently is also used in a few user-facing places, such as: parsing --value's argument, parsing .latest files, and parsing hledger's --version output (which uses unseparated dates).

Unseparated dates were added in 2025 for convenience. Note it means many integers will now parse successfully.

>>> parsedate "2008/02/03"Just 2008-02-03>>> parsedate "2008/02/03/"Nothing>>> parsedate "2008/02/30"Nothing>>> parsedate "2025-01-01"Just 2025-01-01>>> parsedate "2025.01.01"Just 2025-01-01>>> parsedate "20250101"Just 2025-01-01>>> parsedate "00101"Just 0000-01-01

Does the period include the given date ? (Here to avoid import cycle).

Parse a period expression, specifying a date span and optionally a reporting interval. Requires a reference "today" date for resolving any relative start/end dates (only; it is not needed for parsing the reporting interval).

>>> let p = parsePeriodExpr (fromGregorian 2008 11 26)>>> p "from Aug to Oct"Right (NoInterval,DateSpan 2008-08-01..2008-09-30)>>> p "aug to oct"Right (NoInterval,DateSpan 2008-08-01..2008-09-30)>>> p "2009q2"Right (NoInterval,DateSpan 2009Q2)>>> p "Q3"Right (NoInterval,DateSpan 2008Q3)>>> p "every 3 days in Aug"Right (Days 3,DateSpan 2008-08)>>> p "daily from aug"Right (Days 1,DateSpan 2008-08-01..)>>> p "every week to 2009"Right (Weeks 1,DateSpan ..2008-12-31)>>> p "every 2nd day of month"Right (MonthDay 2,DateSpan ..)>>> p "every 2nd day"Right (MonthDay 2,DateSpan ..)>>> p "every 2nd day 2009.."Right (MonthDay 2,DateSpan 2009-01-01..)>>> p "every 2nd day 2009-"Right (MonthDay 2,DateSpan 2009-01-01..)>>> p "every 29th Nov"Right (MonthAndDay 11 29,DateSpan ..)>>> p "every 29th nov ..2009"Right (MonthAndDay 11 29,DateSpan ..2008-12-31)>>> p "every nov 29th"Right (MonthAndDay 11 29,DateSpan ..)>>> p "every Nov 29th 2009.."Right (MonthAndDay 11 29,DateSpan 2009-01-01..)>>> p "every 11/29 from 2009"Right (MonthAndDay 11 29,DateSpan 2009-01-01..)>>> p "every 11/29 since 2009"Right (MonthAndDay 11 29,DateSpan 2009-01-01..)>>> p "every 2nd Thursday of month to 2009"Right (NthWeekdayOfMonth 2 4,DateSpan ..2008-12-31)>>> p "every 1st monday of month to 2009"Right (NthWeekdayOfMonth 1 1,DateSpan ..2008-12-31)>>> p "every tue"Right (DaysOfWeek [2],DateSpan ..)>>> p "every 2nd day of week"Right (DaysOfWeek [2],DateSpan ..)>>> p "every 2nd day of month"Right (MonthDay 2,DateSpan ..)>>> p "every 2nd day"Right (MonthDay 2,DateSpan ..)>>> p "every 2nd day 2009.."Right (MonthDay 2,DateSpan 2009-01-01..)>>> p "every 2nd day of month 2009.."Right (MonthDay 2,DateSpan 2009-01-01..)

Find the previous occurrence of some nth weekday of a month, on or before the given date d.

>>> let wed22nd = fromGregorian 2017 11 22>>> prevNthWeekdayOfMonth 4 3 wed22nd2017-11-22>>> prevNthWeekdayOfMonth 5 2 wed22nd2017-10-31

Render a datespan as a display string, abbreviating into a compact form if possible. Warning, hides whether dates are Exact or Flex.

Like showDateSpan, but show month spans as just the abbreviated month name in the current locale.

Show a DateSpan with its begin/end dates, exact or flex.

Parse a date in any of the formats allowed in Ledger's period expressions, and some others. Assumes any text in the parse stream has been lowercased. Returns a SmartDate, to be converted to a full date later (see fixSmartDate).

Examples:

2004                                        (start of year, which must have 4+ digits)
2004/10                                     (start of month, which must be 1-12)
2004/10/1                                   (exact date, day must be 1-31)
10/1                                        (month and day in current year)
21                                          (day in current month)
october, oct                                (start of month in current year)
yesterday, today, tomorrow                  (-1, 0, 1 days from today)
last/this/next day/week/month/quarter/year  (-1, 0, 1 periods from the current period)
last/this/next monday/mon                   (the previous or next named weekday; this=next)
last/next january/jan                       (previous or next start of named month; this disallowed to avoid confusion)
in n days/weeks/months/quarters/years       (n periods from the current period)
n days/weeks/months/quarters/years ago      (-n periods from the current period)
20181201                                    (8 digit YYYYMMDD with valid year month and day)
201812                                      (6 digit YYYYMM with valid year and month)

Note malformed digit sequences might give surprising results:

201813                                      (6 digits with an invalid month is parsed as start of 6-digit year)
20181301                                    (8 digits with an invalid month is parsed as start of 8-digit year)
20181232                                    (8 digits with an invalid day gives an error)
201801012                                   (9+ digits beginning with a valid YYYYMMDD gives an error)

Eg:

YYYYMMDD is parsed as year-month-date if those parts are valid (>=4 digits, 1-12, and 1-31 respectively): >>> parsewith (smartdate <* eof) "20181201" Right (SmartCompleteDate 2018-12-01)

YYYYMM is parsed as year-month-01 if year and month are valid: >>> parsewith (smartdate <* eof) "201804" Right (SmartAssumeStart 2018 (Just 4))

With an invalid month, it's parsed as a year: >>> parsewith (smartdate <* eof) "201813" Right (SmartAssumeStart 201813 Nothing)

A 9+ digit number beginning with valid YYYYMMDD gives an error: >>> parsewith (smartdate <* eof) "201801012" Left (...)

Big numbers not beginning with a valid YYYYMMDD are parsed as a year: >>> parsewith (smartdate <* eof) "201813012" Right (SmartAssumeStart 201813012 Nothing)

Does the span include the given date ?

Fill any unspecified dates in the first span with the dates from the second one (if specified there). Sort of a one-way spanIntersect. This one can create an invalid span that'll always be empty.

>>> :{ DateSpan (Just $ Exact $ fromGregorian 2024 1 1) Nothing `spanDefaultsFrom` DateSpan (Just $ Exact $ fromGregorian 2024 1 1) (Just $ Exact $ fromGregorian 2024 1 2):}DateSpan 2024-01-01

>>> :{ DateSpan (Just $ Exact $ fromGregorian 2025 1 1) Nothing `spanDefaultsFrom` DateSpan (Just $ Exact $ fromGregorian 2024 1 1) (Just $ Exact $ fromGregorian 2024 1 2):}DateSpan 2025-01-01..2024-01-01

Extend the definite start/end dates of the first span, if needed, to include the definite start/end dates of the second span. Andor, replace open startend dates in the first span with definite start/end dates from the second. Unlike spanUnion, open start/end dates in the second are ignored.

>>> ys2024 = fromGregorian 2024 01 01>>> ys2025 = fromGregorian 2025 01 01>>> to2024 = DateSpan Nothing               (Just $ Exact ys2024)>>> all2024 = DateSpan (Just $ Exact ys2024) (Just $ Exact ys2025)>>> partof2024 = DateSpan (Just $ Exact $ fromGregorian 2024 03 01) (Just $ Exact $ fromGregorian 2024 09 01)>>> spanExtend to2024 all2024DateSpan 2024>>> spanExtend all2024 to2024DateSpan 2024>>> spanExtend partof2024 all2024DateSpan 2024>>> spanExtend all2024 partof2024DateSpan 2024

Calculate the intersection of two datespans.

For non-intersecting spans, gives an empty span beginning on the second's start date: >>> DateSpan (Just $ Flex $ fromGregorian 2018 01 01) (Just $ Flex $ fromGregorian 2018 01 03) spanIntersect DateSpan (Just $ Flex $ fromGregorian 2018 01 03) (Just $ Flex $ fromGregorian 2018 01 05) DateSpan 2018-01-03..2018-01-02

Calculate the union of two datespans. If either span is open-ended, the union will be too.

>>> ys2024 = fromGregorian 2024 01 01>>> ys2025 = fromGregorian 2025 01 01>>> to2024 = DateSpan Nothing               (Just $ Exact ys2024)>>> in2024 = DateSpan (Just $ Exact ys2024) (Just $ Exact ys2025)>>> spanUnion to2024 in2024DateSpan ..2024-12-31>>> spanUnion in2024 to2024DateSpan ..2024-12-31

A smarter version of spanDefaultsFrom that avoids creating invalid spans ending before they begin. Kept separate for now to reduce risk.

>>> :{ DateSpan (Just $ Exact $ fromGregorian 2025 1 1) Nothing `spanValidDefaultsFrom` DateSpan (Just $ Exact $ fromGregorian 2024 1 1) (Just $ Exact $ fromGregorian 2024 1 2):}DateSpan 2025-01-01..

Get the 0-2 years mentioned explicitly in a DateSpan.

Calculate the intersection of a number of datespans.

Get overall span enclosing multiple sequentially ordered spans. The start and end date will be exact or flexible depending on the first span's start date and last span's end date.

Calculate the union of a number of datespans.

Parse a year number from a Text, making sure that at least four digits are used.

Construct a DayPartition from a non-empty list of period boundary dates (start dates plus a final exclusive end date).

>>> boundariesToDayPartition (fromGregorian 2025 01 01 :| [fromGregorian 2025 02 01])DayPartition {dayPartitionToPeriodData = PeriodData{ pdpre = 2024-12-31, pdperiods = fromList [(2025-01-01,2025-01-31)]}}

Construct a DayPartition from a list of period boundary dates (start dates plus a final exclusive end date), if it's a non-empty list.

Find the start and end dates of the period within a DayPartition which contains a given day. If the day is after the end of the last period, it is assumed to be within the last period. If the day is before the start of the first period (ie, in the historical period), only the historical period's end date is returned.

Get this DayPartition's overall start date and end date (both inclusive).

Convert DayPartition to a list of DateSpans. Each span will end one day before the next span begins (the span's exclusive end date will be equal to the next span's start date).

Convert DayPartition to a list (which will always be non-empty) of period start and end dates (both inclusive). Each end date will be one day before the next period's start date.

Convert DayPartition to a non-empty list of period start and end dates (both inclusive). Each end date will be one day before the next period's start date.

Get the natural start for the given interval that falls on or before the given day, when applicable. Works for Weeks, Months, Quarters, Years, eg.

Split a DateSpan into a DayPartition consisting of consecutive exact spans of the specified Interval, or Nothing if the span is invalid. If no interval is specified, the original span is returned. If the original span is the null date span, ie unbounded, Nothing is returned. If the original span is empty, eg if the end date is <= the start date, Nothing is returned.

Date adjustment

Some intervals respect the "adjust" flag (years, quarters, months, weeks, every Nth weekday of month seem to be the ones that need it). This will move the start date earlier, if needed, to the previous natural interval boundary (first of year, first of quarter, first of month, monday, previous Nth weekday of month). Related: #1982 #2218

The end date is always moved later if needed to the next natural interval boundary, so that the last period is the same length as the others.

Examples

>>> let t i y1 m1 d1 y2 m2 d2 = fmap dayPartitionToNonEmpty . splitSpan True i $ DateSpan (Just $ Flex $ fromGregorian y1 m1 d1) (Just $ Flex $ fromGregorian y2 m2 d2)>>> t NoInterval 2008 01 01 2009 01 01Just ((2008-01-01,2008-12-31) :| [])>>> t (Quarters 1) 2008 01 01 2009 01 01Just ((2008-01-01,2008-03-31) :| [(2008-04-01,2008-06-30),(2008-07-01,2008-09-30),(2008-10-01,2008-12-31)])>>> splitSpan True (Quarters 1) nulldatespanNothing>>> t (Days 1) 2008 01 01 2008 01 01  -- an empty datespanNothing>>> t (Quarters 1) 2008 01 01 2008 01 01Nothing>>> t (Months 1) 2008 01 01 2008 04 01Just ((2008-01-01,2008-01-31) :| [(2008-02-01,2008-02-29),(2008-03-01,2008-03-31)])>>> t (Months 2) 2008 01 01 2008 04 01Just ((2008-01-01,2008-02-29) :| [(2008-03-01,2008-04-30)])>>> t (Weeks 1) 2008 01 01 2008 01 15Just ((2007-12-31,2008-01-06) :| [(2008-01-07,2008-01-13),(2008-01-14,2008-01-20)])>>> t (Weeks 2) 2008 01 01 2008 01 15Just ((2007-12-31,2008-01-13) :| [(2008-01-14,2008-01-27)])>>> t (MonthDay 2) 2008 01 01 2008 04 01Just ((2008-01-02,2008-02-01) :| [(2008-02-02,2008-03-01),(2008-03-02,2008-04-01)])>>> t (NthWeekdayOfMonth 2 4) 2011 01 01 2011 02 15Just ((2010-12-09,2011-01-12) :| [(2011-01-13,2011-02-09),(2011-02-10,2011-03-09)])>>> t (DaysOfWeek [2]) 2011 01 01 2011 01 15Just ((2010-12-28,2011-01-03) :| [(2011-01-04,2011-01-10),(2011-01-11,2011-01-17)])>>> t (MonthAndDay 11 29) 2012 10 01 2013 10 15Just ((2012-11-29,2013-11-28) :| [])

Return the union of two DayPartitions if that is a valid DayPartition, or Nothing otherwise.

Given an account name and its account directive, and a problem tag within the latter: render it as a megaparsec-style excerpt, showing the original line number and marked column or region. Returns the file path, line number, column(s) if known, and the rendered excerpt, or as much of these as is possible. The returned columns will be accurate for the rendered error message but not for the original journal data.

From the given posting, make an error excerpt showing the transaction with the balance assertion highlighted.

From the given posting, make an error excerpt showing the transaction with this posting's account part highlighted.

Given a problem posting and a function calculating the best column(s) for marking the error region: look up error info from the parent transaction, and render the transaction as a megaparsec-style excerpt, showing the original line number on the problem posting's line, and a column indicator. Returns the file path, line number, column(s) if known, and the rendered excerpt, or as much of these as is possible. A limitation: columns will be accurate for the rendered error message but not for the original journal data.

Given a problem price directive, and maybe a function to calculate the error region's column(s) (currently ignored): generate a megaparsec-style error message with highlighted excerpt. Returns the source file path, line number, column(s) if known, and the rendered excerpt, or as much of these as possible. Columns will be accurate for the rendered error message, not for the original journal entry.

Given a problem transaction and a function calculating the best column(s) for marking the error region: render it as a megaparsec-style excerpt, showing the original line number on the transaction line, and a column(s) marker. Returns the file path, line number, column(s) if known, and the rendered excerpt, or as much of these as is possible. The returned columns will be accurate for the rendered error message but not for the original journal data.

Find the 1-based index of the first posting in this transaction satisfying the given predicate.

Debug log the ordering of a journal's account declarations (at debug level 7+).

Within each posting's amount, keep only the parts matching the query, and remove any postings with all amounts removed. This can leave unbalanced transactions.

Keep only postings matching the query expression. This can leave unbalanced transactions.

Keep only postings which do not match the query expression, but for which a related posting does. This can leave unbalanced transactions.

Keep only transactions matching the query expression.

Filter out all parts of this posting's amount which do not match the query, and remove the posting if this removes all amounts.

Filter out all parts of this transaction's amounts which do not match the query, and remove any postings with all amounts removed. This can leave the transaction unbalanced.

Convenience/compatibility alias for journalAccountNamesDeclaredOrImplied.

Sorted unique account names declared by account directives in this journal.

Sorted unique account names declared by account directives, or posted to or implied as parents by transactions in this journal.

Sorted unique account names declared by account directives or posted to by transactions in this journal.

Sorted unique account names implied by this journal's transactions - accounts posted to and all their implied parent accounts.

Sorted unique account names posted to by this journal's transactions.

Which tags have been declared explicitly for this account, if any ?

Build a map of all known account types, explicitly declared or inferred from the account's parent or name.

Add a map of all known account types to the journal.

All raw amounts appearing in this journal, with MixedAmounts flattened, in no particular order. (Including from posting amounts, cost amounts, P directives, and the last D directive.)

Apply some account aliases to all posting account names in the journal, as described by accountNameApplyAliases. This can fail due to a bad replacement pattern in a regular expression alias.

The account name to use for conversion postings generated by --infer-equity. This is the first account declared with type V/Conversion, or otherwise the defaultBaseConversionAccount (equity:conversion).

Sorted unique commodity symbols mentioned anywhere in this journal. (Including commodity directives, P directives, the last D directive, posting amounts and cost amounts.)

Sorted unique commodity symbols declared by commodity directives in this journal.

Sorted unique commodity symbols mentioned in this journal's P directives.

Sorted unique commodity symbols used in transactions, in either posting or cost amounts.

Sorted unique commodity symbols used anywhere in this journal, including commodity directives, P directives, the last D directive, posting amounts and cost amounts.

Get the canonical amount styles for this journal, whether (in order of precedence): set globally in InputOpts, declared by commodity directives, declared by a default commodity (D) directive, or inferred from posting amounts, as a map from symbol to style. Styles from directives are assumed to specify the decimal mark.

Like journalCommodityStyles, but attach a particular rounding strategy to the styles, affecting how they will affect display precisions when applied.

Get any tags declared for this commodity.

Merge two journals into one. Transaction counts are summed, map fields are combined, the second's list fields are appended to the first's, the second's parse state is kept.

All the accounts in this journal which are declared or inferred as V/Conversion type. This does not include new account names which might be generated by --infer-equity, currently.

The fully specified exact date span enclosing the dates (primary or secondary) of all this journal's transactions and postings, or DateSpan Nothing Nothing if there are none.

The fully specified date span enclosing the dates (primary and secondary) of all this journal's transactions and postings, or DateSpan Nothing Nothing if there are none.

Unique transaction descriptions used in this journal.

The "exclusive end date" of this journal: the day following its latest transaction or posting date, or Nothing if there are none.

Collect and save inferred amount styles for each commodity based on P directive amounts, posting amounts but not cost amounts, and maybe the last D amount, in that commodity. Can return an error message eg if inconsistent number formats are found.

Add equity postings inferred from costs, where needed and possible. See hledger manual > Cost reporting.

Infer transaction-implied market prices from commodity-exchanging transactions, if any. It's best to call this after transactions have been balanced and posting amounts have appropriate prices attached.

Which tags are in effect for this account, including tags inherited from parent accounts ?

The latest of this journal's transaction and posting dates, or Nothing if there are none.

Sorted unique account names declared or implied in this journal which have no children.

Apply a transformation to a journal's posting amounts.

Apply a transformation to a journal's postings.

Apply a transformation to a journal's transactions.

Apply any transaction modifier rules in the journal (adding automated postings to transactions, eg). Or if a modifier rule fails to parse, return the error message. A reference date is provided to help interpret relative dates in transaction modifier queries. The first argument selects whether to add visible tags to generated postings & modified transactions.

Get the transaction that appeared immediately after this one in the input stream, if any.

Number (set the tindex field) this journal's transactions, counting upward from 1.

Sorted unique payees declared by payee directives in this journal.

Sorted unique payees used in transactions or declared by payee directives in this journal.

Sorted unique payees used by transactions in this journal.

Apply the pivot transformation to all postings in a journal, replacing their account name by their value for the given field or tag.

All posting amounts from this journal, in order.

All raw amounts used in this journal's postings and costs, with MixedAmounts flattened, in parse order.

All postings from this journal's transactions, in order.

To all postings in the journal, add any tags from their account (including those inherited from parent accounts). If a tag already exists on the posting, it is not changed (the account tag will be ignored).

To all postings in the journal, add any tags from their amount's commodities. If a tag already exists on the posting, it is not changed (the commodity tag will be ignored).

Remove all tags from the journal's postings except those provided by their account. This is useful for the accounts report. It does not remove tag declarations from the posting comments.

Get the transaction that appeared immediately before this one in the input stream, if any.

Renumber all the account declarations. This is useful to call when finalising or concatenating Journals, to give account declarations a total order across files.

Reverse all lists of parsed items, which during parsing were prepended to, so that the items are in parse order. Part of post-parse finalisation.

Set this journal's last read time, ie when its files were last read.

The earliest of this journal's transaction and posting dates, or Nothing if there are none.

Apply this journal's commodity display styles to all of its amounts. This does no display rounding, keeping decimal digits as they were; it is suitable for an early cleanup pass before calculations. Reports may want to do additional rounding/styling at render time. This can return an error message eg if inconsistent number formats are found.

Identify and tag (1) equity conversion postings and (2) postings which have (or could have ?) redundant costs. And if the addcosts flag is true, also add any costs which can be inferred from equity conversion postings. This is always called before transaction balancing to tag the redundant-cost postings so they can be ignored. With --infer-costs, it is called again after transaction balancing (when it has more information to work with) to infer costs from equity postings. See transactionTagCostsAndEquityAndMaybeInferCosts for more details, and hledger manual > Cost reporting for more background.

Sorted unique tag names declared by tag directives in this journal.

Sorted unique tag names used in transactions or declared by tag directives in this journal.

Sorted unique tag names used in this journal (in account directives, transactions, postings..)

Convert all this journal's amounts to cost using their attached prices, if any.

Get the transaction with this index (its 1-based position in the input stream), if any.

Find up to N most similar and most recent transactions matching the given transaction description and query and exceeding the given description similarity score (0 to 1, see compareDescriptions). Returns transactions along with their age in days compared to the latest transaction date, their description similarity score, and a heuristically date-weighted variant of this that favours more recent transactions.

Untie all transaction-posting knots in this journal, so that eg recursiveSize and GHCI's :sprint can work on it.

Show the journal posting amounts rendered, suitable for debug logging.

Check that all the journal's postings are to accounts with account directives, returning an error message otherwise.

Check all balance assertions in the journal and return an error message if any of them fail. (Technically, this also tries to balance the journal and can return balancing failure errors; ensure the journal is already balanced (with journalBalanceTransactions) to avoid this.)

Check that all the commodities used in this journal's postings and P directives have been declared by commodity directives, returning an error message otherwise.

In each tranaction, check that any conversion postings occur in adjacent pairs.

Check that all the journal's transactions have payees declared with payee directives, returning an error message otherwise.

Check that accounts with balance assertions have no posting more than maxlag days after their latest balance assertion.

Check that all the journal's tags (on accounts, transactions, postings..) have been declared with tag directives, returning an error message otherwise.

Run the extra -s/--strict checks on a journal, in order of priority, returning the first error message if any of them fail.

Check that all the journal's postings are to accounts with a unique leaf name. Otherwise, return an error message for the first offending posting.

Read a JSON file and decode it to the target type, or raise an error if we can't. Eg: readJsonFile "a.json" :: IO Transaction

Show a JSON-convertible haskell value as pretty-printed JSON text.

Write a JSON-convertible haskell value to a pretty-printed JSON file. Eg: writeJsonFile "a.json" nulltransaction

Get the named account from a ledger.

List a ledger's account names.

All commodities used in this ledger.

The (fully specified) date span containing all the ledger's (filtered) transactions, or DateSpan Nothing Nothing if there are none.

Filter a journal's transactions with the given query, then build a Ledger, containing the journal plus the tree of all its accounts with their subaccount-inclusive and subaccount-exclusive balances. If the query includes a depth limit, the ledger's journal will be depth limited, but the ledger's account tree will not.

List a ledger's bottom-level (subaccount-less) accounts, in tree order.

List a ledger's postings, in the order parsed.

Get this ledger's root account, which is a dummy "root" account above all others. This should always be first in the account list, if somehow not this returns a null account.

List a ledger's top-level accounts (the ones below the root), in tree order.

Convert DateSpans to Periods.

>>> dateSpanAsPeriod $ DateSpan (Just $ Exact $ fromGregorian 2000 1 1) (Just $ Exact $ fromGregorian 2000 2 1)MonthPeriod 2000 1

Is this period a "standard" period, referencing a particular day, week, month, quarter, or year ? Periods of other durations, or infinite duration, or not starting on a standard period boundary, are not.

Convert Periods to exact DateSpans.

>>> periodAsDateSpan (MonthPeriod 2000 1) == DateSpan (Just $ Flex $ fromGregorian 2000 1 1) (Just $ Flex $ fromGregorian 2000 2 1)True

Enlarge a standard period to the next larger enclosing standard period, if there is one. Eg, a day becomes the enclosing week. A week becomes whichever month the week's thursday falls into. A year becomes all (unlimited). Non-standard periods (arbitrary dates, or open-ended) are unaffected.

Move a standard period stepwise so that it encloses the given date. Non-standard periods are unaffected.

Move a standard period to the following period of same duration. Non-standard periods are unaffected.

Move a standard period to the following period of same duration, staying within enclosing dates. Non-standard periods are unaffected.

Move a standard period to the preceding period of same duration. Non-standard periods are unaffected.

Move a standard period to the preceding period of same duration, staying within enclosing dates. Non-standard periods are unaffected.

Shrink a period to the next smaller standard period inside it, choosing the subperiod which contains today's date if possible, otherwise the first subperiod. It goes like this: unbounded periods and nonstandard periods (between two arbitrary dates) -> current year -> current quarter if it's in selected year, otherwise first quarter of selected year -> current month if it's in selected quarter, otherwise first month of selected quarter -> current week if it's in selected month, otherwise first week of selected month -> today if it's in selected week, otherwise first day of selected week, unless that's in previous month, in which case first day of month containing selected week. Shrinking a day has no effect.

The width of a period of this type when displayed.

Render a period as a compact display string suitable for user output.

>>> showPeriod (WeekPeriod (fromGregorian 2016 7 25))"2016-W30">>> showPeriod (WeekPeriod (fromGregorian 2024 12 30))"2025-W01"

Like showPeriod, but if it's a month or week period show an abbreviated form. >>> showPeriodAbbrev (WeekPeriod (fromGregorian 2016 7 25)) W30 >>> showPeriodAbbrev (WeekPeriod (fromGregorian 2024 12 30)) W01

Convert PeriodBetweens to a more abstract period where possible.

>>> simplifyPeriod $ PeriodBetween (fromGregorian 1 1 1) (fromGregorian 2 1 1)YearPeriod 1>>> simplifyPeriod $ PeriodBetween (fromGregorian 2000 10 1) (fromGregorian 2001 1 1)QuarterPeriod 2000 4>>> simplifyPeriod $ PeriodBetween (fromGregorian 2000 2 1) (fromGregorian 2000 3 1)MonthPeriod 2000 2>>> simplifyPeriod $ PeriodBetween (fromGregorian 2016 7 25) (fromGregorian 2016 8 1)WeekPeriod 2016-07-25>>> simplifyPeriod $ PeriodBetween (fromGregorian 2000 1 1) (fromGregorian 2000 1 2)DayPeriod 2000-01-01>>> simplifyPeriod $ PeriodBetween (fromGregorian 2000 2 28) (fromGregorian 2000 3 1)PeriodBetween 2000-02-28 2000-03-01>>> simplifyPeriod $ PeriodBetween (fromGregorian 2000 2 29) (fromGregorian 2000 3 1)DayPeriod 2000-02-29>>> simplifyPeriod $ PeriodBetween (fromGregorian 2000 12 31) (fromGregorian 2001 1 1)DayPeriod 2000-12-31

Set historical or period data in the appropriate location in a PeriodData.

Get the data for the period containing the given Day, and that period's start date. If the day is after the end of the last period, it is assumed to be within the last period. If the day is before the start of the first period (ie, in the historical period), return Nothing.

Get the data for the period containing the given Day, and that period's start date. If the day is after the end of the last period, it is assumed to be within the last period. If the day is before the start of the first period (ie, in the historical period), return the data for the historical period and no start date.