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

Safe Haskell | None
Language | GHC2021

Hledger.Data.Journal

Contents

- Parsing helpers
- Filtering
- Mapping
- Querying
- Account types
- Conversion accounts
- 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
- 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
- journalPostingsAddAccountTags :: Journal -> Journal
- journalPostingsKeepAccountTagsOnly :: Journal -> Journal
- journalPostingsAddCommodityTags :: 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]
- journalAccountNames :: Journal -> [AccountName]
- journalLeafAccountNames :: Journal -> [AccountName]
- journalAccountNameTree :: Journal -> Tree AccountName
- journalAccountTags :: Journal -> AccountName -> [Tag]
- journalCommodityTags :: Journal -> CommoditySymbol -> [Tag]
- journalInheritedAccountTags :: Journal -> AccountName -> [Tag]
- journalPayeesDeclared :: Journal -> [Payee]
- journalPayeesUsed :: Journal -> [Payee]
- journalPayeesDeclaredOrUsed :: Journal -> [Payee]
- journalTagsDeclared :: Journal -> [TagName]
- journalTagsUsed :: Journal -> [TagName]
- journalTagsDeclaredOrUsed :: Journal -> [TagName]
- journalAmounts :: Journal -> Set Amount
- journalPostingAmounts :: Journal -> [MixedAmount]
- journalPostingAndCostAmounts :: Journal -> [Amount]
- journalCommoditiesDeclared :: Journal -> [CommoditySymbol]
- journalCommoditiesUsed :: Journal -> [CommoditySymbol]
- journalCommodities :: Journal -> Set CommoditySymbol
- journalCommoditiesFromPriceDirectives :: Journal -> Set CommoditySymbol
- journalCommoditiesFromTransactions :: 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]
- showJournalPostingAmountsDebug :: 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
- defaultBaseConversionAccount :: IsString a => a
- journalBaseConversionAccount :: Journal -> AccountName
- journalConversionAccounts :: Journal -> [AccountName]
- 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 Source #

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

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

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

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

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

journalDbg :: Journal -> String Source #

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.

journalInferCommodityStyles :: Journal -> Either String Journal Source #

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.

journalStyleAmounts :: Journal -> Either String Journal Source #

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.

journalCommodityStyles :: Journal -> Map CommoditySymbol AmountStyle Source #

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

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

journalToCost :: ConversionOp -> Journal -> Journal Source #

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

journalInferEquityFromCosts :: Bool -> Journal -> Journal Source #

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

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

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

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

journalRenumberAccountDeclarations :: Journal -> Journal Source #

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

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

journalPostingsAddAccountTags :: Journal -> Journal Source #

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

journalPostingsKeepAccountTagsOnly :: Journal -> Journal Source #

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.

journalPostingsAddCommodityTags :: Journal -> Journal Source #

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

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

filterJournalRelatedPostings :: Query -> Journal -> Journal Source #

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

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

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

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

filterTransactionRelatedPostings :: Query -> Transaction -> Transaction Source #

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

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

Apply a transformation to a journal's transactions.

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

Apply a transformation to a journal's postings.

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

Apply a transformation to a journal's posting amounts.

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

journalLeafAccountNames :: Journal -> [AccountName] Source #

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

journalAccountNameTree :: Journal -> Tree AccountName Source #

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

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

journalCommodityTags :: Journal -> CommoditySymbol -> [Tag] Source #

Get any tags declared for this commodity.

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

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

journalPayeesDeclared :: Journal -> [Payee] Source #

Sorted unique payees declared by payee directives in this journal.

journalPayeesUsed :: Journal -> [Payee] Source #

Sorted unique payees used by transactions in this journal.

journalPayeesDeclaredOrUsed :: Journal -> [Payee] Source #

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

journalTagsDeclared :: Journal -> [TagName] Source #

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

journalTagsUsed :: Journal -> [TagName] Source #

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

journalTagsDeclaredOrUsed :: Journal -> [TagName] Source #

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

journalAmounts :: Journal -> Set Amount Source #

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

journalPostingAmounts :: Journal -> [MixedAmount] Source #

All posting amounts from this journal, in order.

journalPostingAndCostAmounts :: Journal -> [Amount] Source #

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

journalCommoditiesDeclared :: Journal -> [CommoditySymbol] Source #

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

journalCommoditiesUsed :: Journal -> [CommoditySymbol] Source #

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

journalCommodities :: Journal -> Set CommoditySymbol Source #

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

journalCommoditiesFromPriceDirectives :: Journal -> Set CommoditySymbol Source #

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

journalCommoditiesFromTransactions :: Journal -> Set CommoditySymbol Source #

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

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

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

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

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

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

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

showJournalPostingAmountsDebug :: Journal -> String Source #

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

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

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

journalAccountTypes :: Journal -> Map AccountName AccountType Source #

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

journalAddAccountTypes :: Journal -> Journal Source #

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

# Conversion accounts

defaultBaseConversionAccount :: IsString a => a Source #

journalBaseConversionAccount :: Journal -> AccountName Source #

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

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

nulljournal :: Journal Source #

journalConcat :: Journal -> Journal -> Journal Source #

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

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

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 :: Bool -> 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. The first argument selects whether to add visible tags to generated postings & modified transactions.

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

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

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

# Tests

samplejournal :: Journal Source #

samplejournalMaybeExplicit :: Bool -> Journal Source #

tests_Journal :: TestTree Source #

# Orphan instances

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