Hledger.Data.Journal

hledger-lib-1.41: A library providing the core functionality of hledger

Safe Haskell | None
Language | Haskell2010

Hledger.Data.Journal

Contents

- Parsing helpers
- Filtering
- Mapping
- Querying
- 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

- type JournalParser (m :: Type -> Type) a = StateT Journal (ParsecT HledgerParseErrorData Text m) a
- type ErroringJournalParser (m :: Type -> Type) a = StateT Journal (ParsecT HledgerParseErrorData Text (ExceptT FinalParseError m)) a
- addPriceDirective :: PriceDirective -> Journal -> Journal
- addTransactionModifier :: TransactionModifier -> Journal -> Journal
- addPeriodicTransaction :: PeriodicTransaction -> Journal -> Journal
- addTransaction :: Transaction -> Journal -> Journal
- journalDbg :: Journal -> String
- journalInferMarketPricesFromTransactions :: Journal -> Journal
- journalInferCommodityStyles :: Journal -> Either String Journal
- journalStyleAmounts :: Journal -> Either String Journal
- commodityStylesFromAmounts :: [Amount] -> Either String (Map CommoditySymbol AmountStyle)
- journalCommodityStyles :: Journal -> Map CommoditySymbol AmountStyle
- journalCommodityStylesWith :: Rounding -> Journal -> Map CommoditySymbol AmountStyle
- journalToCost :: ConversionOp -> Journal -> Journal
- journalInferEquityFromCosts :: Bool -> Journal -> Journal
- journalTagCostsAndEquityAndMaybeInferCosts :: Bool -> Bool -> Journal -> Either String Journal
- journalReverse :: Journal -> Journal
- journalSetLastReadTime :: POSIXTime -> Journal -> Journal
- journalRenumberAccountDeclarations :: Journal -> Journal
- journalPivot :: Text -> Journal -> Journal
- filterJournalTransactions :: Query -> Journal -> Journal
- filterJournalPostings :: Query -> Journal -> Journal
- filterJournalRelatedPostings :: Query -> Journal -> Journal
- filterJournalAmounts :: Query -> Journal -> Journal
- filterTransactionAmounts :: Query -> Transaction -> Transaction
- filterTransactionPostings :: Query -> Transaction -> Transaction
- filterTransactionPostingsExtra :: (AccountName -> Maybe AccountType) -> Query -> Transaction -> Transaction
- filterTransactionRelatedPostings :: Query -> Transaction -> Transaction
- filterPostingAmount :: Query -> Posting -> Maybe Posting
- journalMapTransactions :: (Transaction -> Transaction) -> Journal -> Journal
- journalMapPostings :: (Posting -> Posting) -> Journal -> Journal
- journalMapPostingAmounts :: (MixedAmount -> MixedAmount) -> Journal -> Journal
- journalAccountNamesUsed :: Journal -> [AccountName]
- journalAccountNamesImplied :: Journal -> [AccountName]
- journalAccountNamesDeclared :: Journal -> [AccountName]
- journalAccountNamesDeclaredOrUsed :: Journal -> [AccountName]
- journalAccountNamesDeclaredOrImplied :: Journal -> [AccountName]
- journalLeafAccountNamesDeclared :: Journal -> [AccountName]
- journalAccountNames :: Journal -> [AccountName]
- journalLeafAccountNames :: Journal -> [AccountName]
- journalAccountNameTree :: Journal -> Tree AccountName
- journalAccountTags :: Journal -> AccountName -> [Tag]
- journalInheritedAccountTags :: Journal -> AccountName -> [Tag]
- journalPayeesDeclared :: Journal -> [Payee]
- journalPayeesUsed :: Journal -> [Payee]
- journalPayeesDeclaredOrUsed :: Journal -> [Payee]
- journalTagsDeclared :: Journal -> [TagName]
- journalTagsUsed :: Journal -> [TagName]
- journalTagsDeclaredOrUsed :: Journal -> [TagName]
- journalCommoditiesDeclared :: Journal -> [CommoditySymbol]
- journalCommodities :: Journal -> Set CommoditySymbol
- journalDateSpan :: Bool -> Journal -> DateSpan
- journalDateSpanBothDates :: Journal -> DateSpan
- journalStartDate :: Bool -> Journal -> Maybe Day
- journalEndDate :: Bool -> Journal -> Maybe Day
- journalLastDay :: 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]
- journalPostingAmounts :: Journal -> [MixedAmount]
- showJournalAmountsDebug :: Journal -> String
- journalTransactionsSimilarTo :: Journal -> Text -> Query -> SimilarityScore -> Int -> [(DateWeightedSimilarityScore, Age, SimilarityScore, Transaction)]
- journalAccountType :: Journal -> AccountName -> Maybe AccountType
- journalAccountTypes :: Journal -> Map AccountName AccountType
- journalAddAccountTypes :: Journal -> Journal
- journalPostingsAddAccountTags :: Journal -> Journal
- defaultBaseConversionAccount :: IsString a => a
- journalBaseConversionAccount :: Journal -> AccountName
- journalConversionAccounts :: Journal -> [AccountName]
- canonicalStyleFrom :: [AmountStyle] -> AmountStyle
- nulljournal :: Journal
- journalConcat :: Journal -> Journal -> Journal
- journalNumberTransactions :: Journal -> Journal
- journalNumberAndTieTransactions :: Journal -> Journal
- journalUntieTransactions :: Transaction -> Transaction
- journalModifyTransactions :: Bool -> Day -> Journal -> Either String Journal
- journalApplyAliases :: [AccountAlias] -> Journal -> Either RegexError Journal
- dbgJournalAcctDeclOrder :: String -> Journal -> Journal
- samplejournal :: Journal
- samplejournalMaybeExplicit :: Bool -> Journal
- tests_Journal :: TestTree

# Parsing helpers

type JournalParser (m :: Type -> Type) a = StateT Journal (ParsecT HledgerParseErrorData Text m) a #

A parser of text that runs in some monad, keeping a Journal as state.

type ErroringJournalParser (m :: Type -> Type) a = StateT Journal (ParsecT HledgerParseErrorData Text (ExceptT FinalParseError m)) a #

A parser of text that runs in some monad, keeping a Journal as state, that can throw an exception to end parsing, preventing further parser backtracking.

addPriceDirective :: PriceDirective -> Journal -> Journal #

addTransactionModifier :: TransactionModifier -> Journal -> Journal #

addPeriodicTransaction :: PeriodicTransaction -> Journal -> Journal #

addTransaction :: Transaction -> Journal -> Journal #

journalDbg :: Journal -> String #

journalInferMarketPricesFromTransactions :: Journal -> Journal #

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.

journalInferCommodityStyles :: Journal -> Either String Journal #

Collect and save inferred amount styles for each commodity based on the posting amounts in that commodity (excluding price amounts). Can return an error message eg if inconsistent number formats are found.

journalStyleAmounts :: Journal -> Either String Journal #

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.

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

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 #

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.

journalCommodityStylesWith :: Rounding -> Journal -> Map CommoditySymbol AmountStyle #

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

journalToCost :: ConversionOp -> Journal -> Journal #

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

journalInferEquityFromCosts :: Bool -> Journal -> Journal #

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

journalTagCostsAndEquityAndMaybeInferCosts :: Bool -> Bool -> Journal -> Either String Journal #

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.

journalReverse :: Journal -> Journal #

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 :: POSIXTime -> Journal -> Journal #

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

journalRenumberAccountDeclarations :: Journal -> Journal #

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

journalPivot :: Text -> Journal -> Journal #

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 #

Keep only transactions matching the query expression.

filterJournalPostings :: Query -> Journal -> Journal #

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

filterJournalRelatedPostings :: Query -> Journal -> Journal #

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

filterJournalAmounts :: Query -> Journal -> Journal #

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.

filterTransactionAmounts :: Query -> Transaction -> Transaction #

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.

filterTransactionPostings :: Query -> Transaction -> Transaction #

filterTransactionPostingsExtra :: (AccountName -> Maybe AccountType) -> Query -> Transaction -> Transaction #

filterTransactionRelatedPostings :: Query -> Transaction -> Transaction #

filterPostingAmount :: Query -> Posting -> Maybe Posting #

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

# Mapping

journalMapTransactions :: (Transaction -> Transaction) -> Journal -> Journal #

Apply a transformation to a journal's transactions.

journalMapPostings :: (Posting -> Posting) -> Journal -> Journal #

Apply a transformation to a journal's postings.

journalMapPostingAmounts :: (MixedAmount -> MixedAmount) -> Journal -> Journal #

Apply a transformation to a journal's posting amounts.

# Querying

journalAccountNamesUsed :: Journal -> [AccountName] #

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

journalAccountNamesImplied :: Journal -> [AccountName] #

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

journalAccountNamesDeclared :: Journal -> [AccountName] #

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

journalAccountNamesDeclaredOrUsed :: Journal -> [AccountName] #

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

journalAccountNamesDeclaredOrImplied :: Journal -> [AccountName] #

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

journalLeafAccountNamesDeclared :: Journal -> [AccountName] #

Sorted unique account names declared by account directives in this journal, which have no children.

journalAccountNames :: Journal -> [AccountName] #

Convenience/compatibility alias for journalAccountNamesDeclaredOrImplied.

journalLeafAccountNames :: Journal -> [AccountName] #

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

journalAccountNameTree :: Journal -> Tree AccountName #

journalAccountTags :: Journal -> AccountName -> [Tag] #

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

journalInheritedAccountTags :: Journal -> AccountName -> [Tag] #

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

journalPayeesDeclared :: Journal -> [Payee] #

Sorted unique payees declared by payee directives in this journal.

journalPayeesUsed :: Journal -> [Payee] #

Sorted unique payees used by transactions in this journal.

journalPayeesDeclaredOrUsed :: Journal -> [Payee] #

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

journalTagsDeclared :: Journal -> [TagName] #

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

journalTagsUsed :: Journal -> [TagName] #

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

journalTagsDeclaredOrUsed :: Journal -> [TagName] #

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

journalCommoditiesDeclared :: Journal -> [CommoditySymbol] #

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

journalCommodities :: Journal -> Set CommoditySymbol #

Sorted unique commodity symbols mentioned in this journal.

journalDateSpan :: Bool -> Journal -> DateSpan #

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.

journalDateSpanBothDates :: Journal -> DateSpan #

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.

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

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

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

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

journalLastDay :: Bool -> Journal -> Maybe Day #

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

journalDescriptions :: Journal -> [Text] #

Unique transaction descriptions used in this journal.

journalFilePath :: Journal -> FilePath #

journalFilePaths :: Journal -> [FilePath] #

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

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

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

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

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

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

journalPostings :: Journal -> [Posting] #

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

journalPostingAmounts :: Journal -> [MixedAmount] #

All posting amounts from this journal, in order.

showJournalAmountsDebug :: Journal -> String #

Show the journal amounts rendered, suitable for debug logging.

journalTransactionsSimilarTo :: Journal -> Text -> Query -> SimilarityScore -> Int -> [(DateWeightedSimilarityScore, Age, SimilarityScore, Transaction)] #

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.

# Account types

journalAccountType :: Journal -> AccountName -> Maybe AccountType #

journalAccountTypes :: Journal -> Map AccountName AccountType #

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

journalAddAccountTypes :: Journal -> Journal #

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

journalPostingsAddAccountTags :: Journal -> Journal #

To all postings in the journal, add any tags from their account (including those inherited from parent accounts). If the same tag exists on posting and account, the latter is ignored.

defaultBaseConversionAccount :: IsString a => a #

journalBaseConversionAccount :: Journal -> AccountName #

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

journalConversionAccounts :: Journal -> [AccountName] #

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.

# Misc

canonicalStyleFrom :: [AmountStyle] -> AmountStyle #

Given a list of amount styles (assumed to be from parsed amounts in a single commodity), in parse order, choose a canonical style.

nulljournal :: Journal #

journalConcat :: Journal -> Journal -> Journal #

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.

journalNumberTransactions :: Journal -> Journal #

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

journalNumberAndTieTransactions :: Journal -> Journal #

journalUntieTransactions :: Transaction -> Transaction #

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

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

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.

journalApplyAliases :: [AccountAlias] -> Journal -> Either RegexError Journal #

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.

dbgJournalAcctDeclOrder :: String -> Journal -> Journal #

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

# Tests

samplejournal :: Journal #

samplejournalMaybeExplicit :: Bool -> Journal #

tests_Journal :: TestTree #

# Orphan instances

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