hledger-lib-1.19.1: A reusable library providing the core functionality of hledger

Safe Haskell | None
Language | Haskell2010

Hledger.Data.Journal

Contents

- Parsing helpers
- Filtering
- Mapping
- Querying
- Standard account types
- Misc
- Tests
- Orphan instances

Description

A `Journal` is a set of transactions, plus optional related data. This is hledger's primary data object. It is usually parsed from a journal file or other data format (see Hledger.Read).

Synopsis

- addPriceDirective :: PriceDirective -> Journal -> Journal
- addTransactionModifier :: TransactionModifier -> Journal -> Journal
- addPeriodicTransaction :: PeriodicTransaction -> Journal -> Journal
- addTransaction :: Transaction -> Journal -> Journal
- journalBalanceTransactions :: Bool -> Journal -> Either String Journal
- journalInferMarketPricesFromTransactions :: Journal -> Journal
- journalApplyCommodityStyles :: Journal -> Either String Journal
- commodityStylesFromAmounts :: [Amount] -> Either String (Map CommoditySymbol AmountStyle)
- journalCommodityStyles :: Journal -> Map CommoditySymbol AmountStyle
- journalToCost :: Journal -> Journal
- journalReverse :: Journal -> Journal
- journalSetLastReadTime :: ClockTime -> Journal -> Journal
- journalPivot :: Text -> Journal -> Journal
- filterJournalTransactions :: Query -> Journal -> Journal
- filterJournalPostings :: Query -> Journal -> Journal
- filterJournalAmounts :: Query -> Journal -> Journal
- filterTransactionAmounts :: Query -> Transaction -> Transaction
- filterTransactionPostings :: Query -> Transaction -> Transaction
- filterPostingAmount :: Query -> Posting -> Posting
- mapJournalTransactions :: (Transaction -> Transaction) -> Journal -> Journal
- mapJournalPostings :: (Posting -> Posting) -> Journal -> Journal
- mapTransactionPostings :: (Posting -> Posting) -> Transaction -> Transaction
- journalAccountNamesUsed :: Journal -> [AccountName]
- journalAccountNamesImplied :: Journal -> [AccountName]
- journalAccountNamesDeclared :: Journal -> [AccountName]
- journalAccountNamesDeclaredOrUsed :: Journal -> [AccountName]
- journalAccountNamesDeclaredOrImplied :: Journal -> [AccountName]
- journalAccountNames :: Journal -> [AccountName]
- journalDateSpan :: Bool -> Journal -> DateSpan
- journalStartDate :: Bool -> Journal -> Maybe Day
- journalEndDate :: Bool -> Journal -> Maybe Day
- journalDescriptions :: Journal -> [Text]
- journalFilePath :: Journal -> FilePath
- journalFilePaths :: Journal -> [FilePath]
- journalTransactionAt :: Journal -> Integer -> Maybe Transaction
- journalNextTransaction :: Journal -> Transaction -> Maybe Transaction
- journalPrevTransaction :: Journal -> Transaction -> Maybe Transaction
- journalPostings :: Journal -> [Posting]
- journalBalanceSheetAccountQuery :: Journal -> Query
- journalProfitAndLossAccountQuery :: Journal -> Query
- journalRevenueAccountQuery :: Journal -> Query
- journalExpenseAccountQuery :: Journal -> Query
- journalAssetAccountQuery :: Journal -> Query
- journalLiabilityAccountQuery :: Journal -> Query
- journalEquityAccountQuery :: Journal -> Query
- journalCashAccountQuery :: Journal -> Query
- canonicalStyleFrom :: [AmountStyle] -> AmountStyle
- nulljournal :: Journal
- journalCheckBalanceAssertions :: Journal -> Maybe String
- journalNumberAndTieTransactions :: Journal -> Journal
- journalUntieTransactions :: Transaction -> Transaction
- journalModifyTransactions :: Day -> Journal -> Either String Journal
- samplejournal :: Journal
- tests_Journal :: TestTree

# Parsing helpers

addPriceDirective :: PriceDirective -> Journal -> Journal Source #

addTransactionModifier :: TransactionModifier -> Journal -> Journal Source #

addPeriodicTransaction :: PeriodicTransaction -> Journal -> Journal Source #

addTransaction :: Transaction -> Journal -> Journal Source #

journalBalanceTransactions :: Bool -> Journal -> Either String Journal Source #

Infer any missing amounts (to satisfy balance assignments and to balance transactions) and check that all transactions balance and (optional) all balance assertions pass. Or return an error message (just the first error encountered).

Assumes journalInferCommodityStyles has been called, since those affect transaction balancing.

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

journalInferMarketPricesFromTransactions :: Journal -> Journal Source #

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.

journalApplyCommodityStyles :: Journal -> Either String Journal Source #

Choose and apply a consistent display style to the posting amounts in each commodity. Each commodity's style is specified by a commodity (or D) directive, or otherwise inferred from posting amounts. Can return an error message eg if inconsistent number formats are found.

commodityStylesFromAmounts :: [Amount] -> Either String (Map CommoditySymbol AmountStyle) Source #

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.

journalCommodityStyles :: Journal -> Map CommoditySymbol AmountStyle Source #

Get the canonical amount styles for this journal, whether declared by commodity directives, by the last default commodity (D) directive, or inferred from posting amounts, as a map from symbol to style. Styles declared by directives take precedence (and commodity takes precedence over D). Styles from directives are guaranteed to specify the decimal mark character.

journalToCost :: Journal -> Journal Source #

Convert all this journal's amounts to cost using the transaction prices, if any. The journal's commodity styles are applied to the resulting amounts.

journalReverse :: Journal -> Journal Source #

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.

journalSetLastReadTime :: ClockTime -> Journal -> Journal Source #

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

journalPivot :: Text -> Journal -> Journal Source #

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

# Filtering

filterJournalTransactions :: Query -> Journal -> Journal Source #

Keep only transactions matching the query expression.

filterJournalPostings :: Query -> Journal -> Journal Source #

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

filterJournalAmounts :: Query -> Journal -> Journal Source #

Within each posting's amount, keep only the parts matching the query. This can leave unbalanced transactions.

filterTransactionAmounts :: Query -> Transaction -> Transaction Source #

Filter out all parts of this transaction's amounts which do not match the query. This can leave the transaction unbalanced.

filterTransactionPostings :: Query -> Transaction -> Transaction Source #

filterPostingAmount :: Query -> Posting -> Posting Source #

Filter out all parts of this posting's amount which do not match the query.

# Mapping

mapJournalTransactions :: (Transaction -> Transaction) -> Journal -> Journal Source #

Apply a transformation to a journal's transactions.

mapJournalPostings :: (Posting -> Posting) -> Journal -> Journal Source #

Apply a transformation to a journal's postings.

mapTransactionPostings :: (Posting -> Posting) -> Transaction -> Transaction Source #

Apply a transformation to a transaction's postings.

# Querying

journalAccountNamesUsed :: Journal -> [AccountName] Source #

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

journalAccountNamesImplied :: Journal -> [AccountName] Source #

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

journalAccountNamesDeclared :: Journal -> [AccountName] Source #

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

journalAccountNamesDeclaredOrUsed :: Journal -> [AccountName] Source #

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

journalAccountNamesDeclaredOrImplied :: Journal -> [AccountName] Source #

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

journalAccountNames :: Journal -> [AccountName] Source #

Convenience/compatibility alias for journalAccountNamesDeclaredOrImplied.

journalDateSpan :: Bool -> Journal -> DateSpan Source #

Get an ordered list of `AmountStyle`s from the amounts in this journal which influence canonical amount display styles. See traverseJournalAmounts. journalAmounts :: Journal -> [Amount] journalAmounts = getConst . traverseJournalAmounts (Const . (:[]))

| Apply a transformation to the journal amounts traversed by traverseJournalAmounts. overJournalAmounts :: (Amount -> Amount) -> Journal -> Journal overJournalAmounts f = runIdentity . traverseJournalAmounts (Identity . f)

| A helper that traverses over most amounts in the journal, in particular the ones which influence canonical amount display styles, processing them with the given applicative function.

These include, in the following order:

- the amount in the final default commodity (D) directive
- amounts in market price (P) directives (in parse order)
- posting amounts in transactions (in parse order)

Transaction price amounts, which may be embedded in posting amounts (the aprice field), are left intact but not traversed/processed.

traverseJournalAmounts :: Applicative f => (Amount -> f Amount) -> Journal -> f Journal traverseJournalAmounts f j = recombine $ (traverse . dcamt) f (jparsedefaultcommodity j) * (traverse . pdamt) f (jpricedirectives j) * (traverse . tps . traverse . pamt . amts . traverse) f (jtxns j) where recombine pds txns = j { jpricedirectives = pds, jtxns = txns } -- a bunch of traversals dcamt g pd = (mdc -> case mdc of Nothing -> Nothing Just ((c,stpd{pdamount =amt} ) $ g (pdamount pd) pdamt g pd = (amt -> pd{pdamount =amt}) $ g (pdamount pd) tps g t = (ps -> t {tpostings=ps }) $ g (tpostings t) pamt g p = (amt -> p {pamount =amt}) $ g (pamount p) amts g (Mixed as) = Mixed $ g as

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

journalStartDate :: Bool -> Journal -> Maybe Day Source #

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

journalEndDate :: Bool -> Journal -> Maybe Day Source #

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

journalDescriptions :: Journal -> [Text] Source #

Unique transaction descriptions used in this journal.

journalFilePath :: Journal -> FilePath Source #

journalFilePaths :: Journal -> [FilePath] Source #

journalTransactionAt :: Journal -> Integer -> Maybe Transaction Source #

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

journalNextTransaction :: Journal -> Transaction -> Maybe Transaction Source #

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

journalPrevTransaction :: Journal -> Transaction -> Maybe Transaction Source #

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

journalPostings :: Journal -> [Posting] Source #

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

# Standard account types

journalBalanceSheetAccountQuery :: Journal -> Query Source #

A query for Asset, Liability & Equity accounts in this journal. Cf http://en.wikipedia.org/wiki/Chart_of_accounts#Balance_Sheet_Accounts.

journalProfitAndLossAccountQuery :: Journal -> Query Source #

A query for Profit & Loss accounts in this journal. Cf http://en.wikipedia.org/wiki/Chart_of_accounts#Profit_.26_Loss_accounts.

journalRevenueAccountQuery :: Journal -> Query Source #

A query for accounts in this journal which have been declared as Revenue by account directives, or otherwise for accounts with names matched by the case-insensitive regular expression `^(income|revenue)s?(:|$)`.

journalExpenseAccountQuery :: Journal -> Query Source #

A query for accounts in this journal which have been declared as Expense by account directives, or otherwise for accounts with names matched by the case-insensitive regular expression `^expenses?(:|$)`.

journalAssetAccountQuery :: Journal -> Query Source #

A query for accounts in this journal which have been declared as Asset (or Cash, a subtype of Asset) by account directives, or otherwise for accounts with names matched by the case-insensitive regular expression `^assets?(:|$)`.

journalLiabilityAccountQuery :: Journal -> Query Source #

A query for accounts in this journal which have been declared as Liability by account directives, or otherwise for accounts with names matched by the case-insensitive regular expression `^(debts?|liabilit(y|ies))(:|$)`.

journalEquityAccountQuery :: Journal -> Query Source #

A query for accounts in this journal which have been declared as Equity by account directives, or otherwise for accounts with names matched by the case-insensitive regular expression `^equity(:|$)`.

journalCashAccountQuery :: Journal -> Query Source #

A query for Cash (liquid asset) accounts in this journal, ie accounts declared as Cash by account directives, or otherwise with names matched by the case-insensitive regular expression `^assets?(:|$)`. and not including the case-insensitive regular expression `(investment|receivable|:A/R|:fixed)`.

# Misc

canonicalStyleFrom :: [AmountStyle] -> AmountStyle Source #

Given a list of amount styles (assumed to be from parsed amounts in a single commodity), in parse order, choose a canonical style. Traditionally it's "the style of the first, with the maximum precision of all".

nulljournal :: Journal Source #

journalCheckBalanceAssertions :: Journal -> Maybe String Source #

Check any balance assertions in the journal and return an error message if any of them fail (or if the transaction balancing they require fails).

journalNumberAndTieTransactions :: Journal -> Journal Source #

journalUntieTransactions :: Transaction -> Transaction Source #

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

journalModifyTransactions :: Day -> Journal -> Either String Journal Source #

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.

# Tests

samplejournal :: Journal Source #

tests_Journal :: TestTree Source #

# Orphan instances

Show Journal Source # |
Instance details Methods showsPrec :: Int -> Journal -> ShowS Source # show :: Journal -> String Source # showList :: [Journal] -> ShowS Source #
Semigroup Journal Source # |
Instance details Methods (<>) :: Journal -> Journal -> Journal Source # sconcat :: NonEmpty Journal -> Journal Source # stimes :: Integral b => b -> Journal -> Journal Source #
Default Journal Source # |
Instance details Methods def :: Journal #