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

Safe Haskell | None
Language | GHC2021

Hledger.Data.Transaction

Contents

- Transaction
- operations
- helpers
- date operations
- transaction description parts
- rendering
- transaction errors
- tests
- Orphan instances

Description

A `Transaction` represents a movement of some commodity(ies) between two or more accounts. It consists of multiple account `Posting`s which balance to zero, a date, and optional extras like description, cleared status, and tags.

Synopsis

- nulltransaction :: Transaction
- transaction :: Day -> [Posting] -> Transaction
- txnTieKnot :: Transaction -> Transaction
- txnUntieKnot :: Transaction -> Transaction
- hasRealPostings :: Transaction -> Bool
- realPostings :: Transaction -> [Posting]
- assignmentPostings :: Transaction -> [Posting]
- virtualPostings :: Transaction -> [Posting]
- balancedVirtualPostings :: Transaction -> [Posting]
- transactionsPostings :: [Transaction] -> [Posting]
- transactionTransformPostings :: (Posting -> Posting) -> Transaction -> Transaction
- transactionApplyValuation :: PriceOracle -> Map CommoditySymbol AmountStyle -> Day -> Day -> ValuationType -> Transaction -> Transaction
- transactionToCost :: ConversionOp -> Transaction -> Transaction
- transactionInferEquityPostings :: Bool -> AccountName -> Transaction -> Transaction
- transactionTagCostsAndEquityAndMaybeInferCosts :: Bool -> Bool -> [AccountName] -> Transaction -> Either String Transaction
- transactionApplyAliases :: [AccountAlias] -> Transaction -> Either RegexError Transaction
- transactionMapPostings :: (Posting -> Posting) -> Transaction -> Transaction
- transactionMapPostingAmounts :: (MixedAmount -> MixedAmount) -> Transaction -> Transaction
- transactionAmounts :: Transaction -> [MixedAmount]
- transactionCommodityStyles :: Transaction -> Map CommoditySymbol AmountStyle
- transactionCommodityStylesWith :: Rounding -> Transaction -> Map CommoditySymbol AmountStyle
- transactionNegate :: Transaction -> Transaction
- partitionAndCheckConversionPostings :: Bool -> [AccountName] -> [IdxPosting] -> Either Text ([(IdxPosting, IdxPosting)], ([IdxPosting], [IdxPosting]))
- transactionAddTags :: Transaction -> [Tag] -> Transaction
- transactionAddHiddenAndMaybeVisibleTag :: Bool -> HiddenTag -> Transaction -> Transaction
- data TransactionBalancingPrecision
  - = TBPOld
  - | TBPExact
- payeeAndNoteFromDescription :: Text -> (Text, Text)
- payeeAndNoteFromDescription' :: Text -> (Text, Text)
- transactionDate2 :: Transaction -> Day
- transactionDateOrDate2 :: WhichDate -> Transaction -> Day
- transactionPayee :: Transaction -> Text
- transactionNote :: Transaction -> Text
- showTransaction :: Transaction -> Text
- showTransactionOneLineAmounts :: Transaction -> Text
- showTransactionLineFirstPart :: Transaction -> Text
- transactionFile :: Transaction -> FilePath
- annotateErrorWithTransaction :: Transaction -> String -> String
- tests_Transaction :: TestTree

# Transaction

nulltransaction :: Transaction Source #

transaction :: Day -> [Posting] -> Transaction Source #

Make a simple transaction with the given date and postings.

txnTieKnot :: Transaction -> Transaction Source #

Ensure a transaction's postings refer back to it, so that eg relatedPostings works right.

txnUntieKnot :: Transaction -> Transaction Source #

Ensure a transaction's postings do not refer back to it, so that eg recursiveSize and GHCI's :sprint work right.

# operations

hasRealPostings :: Transaction -> Bool Source #

realPostings :: Transaction -> [Posting] Source #

assignmentPostings :: Transaction -> [Posting] Source #

virtualPostings :: Transaction -> [Posting] Source #

balancedVirtualPostings :: Transaction -> [Posting] Source #

transactionsPostings :: [Transaction] -> [Posting] Source #

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

Apply a transform function to this transaction's amounts.

transactionApplyValuation :: PriceOracle -> Map CommoditySymbol AmountStyle -> Day -> Day -> ValuationType -> Transaction -> Transaction Source #

Apply a specified valuation to this transaction's amounts, using the provided price oracle, commodity styles, and reference dates. See amountApplyValuation.

transactionToCost :: ConversionOp -> Transaction -> Transaction Source #

Maybe convert this `Transaction`s amounts to cost.

transactionInferEquityPostings :: Bool -> AccountName -> Transaction -> Transaction Source #

For any costs in this `Transaction` which don't have associated equity conversion postings, generate and add those.

transactionTagCostsAndEquityAndMaybeInferCosts :: Bool -> Bool -> [AccountName] -> Transaction -> Either String Transaction Source #

Find, associate, and tag the corresponding equity conversion postings and costful or potentially costful postings in this transaction. With a true addcosts argument, also generate and add any equivalent costs that are missing. The (previously detected) names of all equity conversion accounts should be provided.

For every pair of adjacent conversion postings, this first searches for a posting with equivalent cost (1). If no such posting is found, it then searches the costless postings, for one matching one of the conversion amounts (2). If either of these found a candidate posting, it is tagged with costPostingTagName. Then if in addcosts mode, if a costless posting was found, a cost equivalent to the conversion amounts is added to it.

The name reflects the complexity of this and its helpers; clarification is ongoing.

transactionApplyAliases :: [AccountAlias] -> Transaction -> Either RegexError Transaction Source #

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

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

Apply a transformation to a transaction's postings.

transactionMapPostingAmounts :: (MixedAmount -> MixedAmount) -> Transaction -> Transaction Source #

Apply a transformation to a transaction's posting amounts.

transactionAmounts :: Transaction -> [MixedAmount] Source #

All posting amounts from this transaction, in order.

transactionCommodityStyles :: Transaction -> Map CommoditySymbol AmountStyle Source #

Get the canonical amount styles inferred from this transaction's amounts.

transactionCommodityStylesWith :: Rounding -> Transaction -> Map CommoditySymbol AmountStyle Source #

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

transactionNegate :: Transaction -> Transaction Source #

Flip the sign of this transaction's posting amounts (and balance assertion amounts).

partitionAndCheckConversionPostings :: Bool -> [AccountName] -> [IdxPosting] -> Either Text ([(IdxPosting, IdxPosting)], ([IdxPosting], [IdxPosting])) Source #

transactionAddTags :: Transaction -> [Tag] -> Transaction Source #

Add tags to a transaction, discarding any for which it already has a value. Note this does not add tags to the transaction's comment.

transactionAddHiddenAndMaybeVisibleTag :: Bool -> HiddenTag -> Transaction -> Transaction Source #

Add the given hidden tag to a transaction; and with a true argument, also add the equivalent visible tag to the transaction's tags and comment fields. If the transaction already has these tags (with any value), do nothing.

# helpers

data TransactionBalancingPrecision Source #

How to determine the precision used for checking that transactions are balanced. See #2402.

Constructors

TBPOld

Legacy behaviour, as in hledger <1.50, included to ease upgrades. use precision inferred from the whole journal, overridable by commodity directive or -c. Display precision is also transaction balancing precision; increasing it can break journal reading. Some valid journals are rejected until commodity directives are added. Small unbalanced remainders can be hidden, and in accounts that are never reconciled, can accumulate over time.

TBPExact

Simpler, more robust behaviour, as in Ledger: use precision inferred from the transaction. Display precision and transaction balancing precision are independent; display precision never affects journal reading. Valid journals from ledger or beancount are accepted without needing commodity directives. Every imbalance in a transaction is visibly accounted for in that transaction's journal entry.

#### Instances

Instances details

Bounded TransactionBalancingPrecision Source # |
Instance details Defined in Hledger.Data.Transaction Methods minBound :: TransactionBalancingPrecision Source # maxBound :: TransactionBalancingPrecision Source #
Enum TransactionBalancingPrecision Source # |

Instance details

Defined in Hledger.Data.Transaction

Methods

succ :: TransactionBalancingPrecision -> TransactionBalancingPrecision Source #

pred :: TransactionBalancingPrecision -> TransactionBalancingPrecision Source #

toEnum :: Int -> TransactionBalancingPrecision Source #

fromEnum :: TransactionBalancingPrecision -> Int Source #

enumFrom :: TransactionBalancingPrecision -> [TransactionBalancingPrecision] Source #

enumFromThen :: TransactionBalancingPrecision -> TransactionBalancingPrecision -> [TransactionBalancingPrecision] Source #

enumFromTo :: TransactionBalancingPrecision -> TransactionBalancingPrecision -> [TransactionBalancingPrecision] Source #

enumFromThenTo :: TransactionBalancingPrecision -> TransactionBalancingPrecision -> TransactionBalancingPrecision -> [TransactionBalancingPrecision] Source #

Read TransactionBalancingPrecision Source # |
Instance details Defined in Hledger.Data.Transaction Methods readsPrec :: Int -> ReadS TransactionBalancingPrecision Source # readList :: ReadS [TransactionBalancingPrecision] Source # readPrec :: ReadPrec TransactionBalancingPrecision Source # readListPrec :: ReadPrec [TransactionBalancingPrecision] Source #
Show TransactionBalancingPrecision Source # |
Instance details Defined in Hledger.Data.Transaction Methods showsPrec :: Int -> TransactionBalancingPrecision -> ShowS Source # show :: TransactionBalancingPrecision -> String Source # showList :: [TransactionBalancingPrecision] -> ShowS Source #
Eq TransactionBalancingPrecision Source # |
Instance details Defined in Hledger.Data.Transaction Methods (==) :: TransactionBalancingPrecision -> TransactionBalancingPrecision -> Bool Source # (/=) :: TransactionBalancingPrecision -> TransactionBalancingPrecision -> Bool Source #
Ord TransactionBalancingPrecision Source # |

Instance details

Defined in Hledger.Data.Transaction

Methods

compare :: TransactionBalancingPrecision -> TransactionBalancingPrecision -> Ordering Source #

(<) :: TransactionBalancingPrecision -> TransactionBalancingPrecision -> Bool Source #

(<=) :: TransactionBalancingPrecision -> TransactionBalancingPrecision -> Bool Source #

(>) :: TransactionBalancingPrecision -> TransactionBalancingPrecision -> Bool Source #

(>=) :: TransactionBalancingPrecision -> TransactionBalancingPrecision -> Bool Source #

max :: TransactionBalancingPrecision -> TransactionBalancingPrecision -> TransactionBalancingPrecision Source #

min :: TransactionBalancingPrecision -> TransactionBalancingPrecision -> TransactionBalancingPrecision Source #

payeeAndNoteFromDescription :: Text -> (Text, Text) Source #

Parse a transaction's description into payee and note (aka narration) fields, assuming a convention of separating these with | (like Beancount). Ie, everything up to the first | is the payee, everything after it is the note. When there's no |, payee == note == description.

payeeAndNoteFromDescription' :: Text -> (Text, Text) Source #

Like payeeAndNoteFromDescription, but if there's no | then payee is empty.

# date operations

transactionDate2 :: Transaction -> Day Source #

transactionDateOrDate2 :: WhichDate -> Transaction -> Day Source #

# transaction description parts

transactionPayee :: Transaction -> Text Source #

transactionNote :: Transaction -> Text Source #

# rendering

showTransaction :: Transaction -> Text Source #

Render a journal transaction as text similar to the style of Ledger's print command.

Adapted from Ledger 2.x and 3.x standard format:

    yyyy-mm-dd[ *][ CODE] description.........          [  ; comment...............]
        account name 1.....................  ...$amount1[  ; comment...............]
        account name 2.....................  ..$-amount1[  ; comment...............]

    pcodewidth    = no limit -- 10          -- mimicking ledger layout.
    pdescwidth    = no limit -- 20          -- I don't remember what these mean,
    pacctwidth    = 35 minimum, no maximum  -- they were important at the time.
    pamtwidth     = 11
    pcommentwidth = no limit -- 22

The output will be parseable journal syntax. To facilitate this, postings with explicit multi-commodity amounts are displayed as multiple similar postings, one per commodity. (Normally does not happen with this function).

showTransactionOneLineAmounts :: Transaction -> Text Source #

Like showTransaction, but explicit multi-commodity amounts are shown on one line, comma-separated. In this case the output will not be parseable journal syntax.

showTransactionLineFirstPart :: Transaction -> Text Source #

transactionFile :: Transaction -> FilePath Source #

The file path from which this transaction was parsed.

# transaction errors

annotateErrorWithTransaction :: Transaction -> String -> String Source #

# tests

tests_Transaction :: TestTree Source #

# Orphan instances

HasAmounts Transaction Source # |
Instance details Methods styleAmounts :: Map CommoditySymbol AmountStyle -> Transaction -> Transaction Source #