Hledger.Data.Transaction

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

Transaction

nulltransaction :: Transaction

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

Make a simple transaction with the given date and postings.

txnTieKnot :: Transaction -> Transaction

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

txnUntieKnot :: Transaction -> Transaction

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

transactionCheckBalanced :: BalancingOpts -> Transaction -> [String]

Check that this transaction would appear balanced to a human when displayed. On success, returns the empty list, otherwise one or more error messages.

In more detail: For the real postings, and separately for the balanced virtual postings:

1. Convert amounts to cost where possible
2. When there are two or more non-zero amounts (appearing non-zero when displayed, using the given display styles if provided), are they a mix of positives and negatives ? This is checked separately to give a clearer error message. (Best effort; could be confused by postings with multicommodity amounts.)
3. Does the amounts' sum appear non-zero when displayed ? (using the given display styles if provided)

operations

showAccountName :: Maybe Int -> PostingType -> AccountName -> Text

Show an account name, clipped to the given width if any, and appropriately bracketed/parenthesised for the given posting type.

hasRealPostings :: Transaction -> Bool

realPostings :: Transaction -> [Posting]

assignmentPostings :: Transaction -> [Posting]

virtualPostings :: Transaction -> [Posting]

balancedVirtualPostings :: Transaction -> [Posting]

transactionsPostings :: [Transaction] -> [Posting]

data BalancingOpts

Constructors

BalancingOpts

Fields

• ignore_assertions_ :: Bool

  Ignore balance assertions

• infer_prices_ :: Bool

  Infer prices in unbalanced multicommodity amounts

• commodity_styles_ :: Maybe (Map CommoditySymbol AmountStyle)

  commodity display styles

Instances

Show BalancingOpts

Defined in Hledger.Data.Transaction

Methods

showsPrec :: Int -> BalancingOpts -> ShowS

show :: BalancingOpts -> String

showList :: [BalancingOpts] -> ShowS

Default BalancingOpts

Defined in Hledger.Data.Transaction

Methods

def :: BalancingOpts

balancingOpts :: BalancingOpts

isTransactionBalanced :: BalancingOpts -> Transaction -> Bool

Legacy form of transactionCheckBalanced.

balanceTransaction :: BalancingOpts -> Transaction -> Either String Transaction

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

Transactions with balance assignments can have more than one missing amount; to balance those you should use the more powerful journalBalanceTransactions.

The "sum to 0" test is done using commodity display precisions, if provided, so that the result agrees with the numbers users can see.

balanceTransactionHelper :: BalancingOpts -> Transaction -> Either String (Transaction, [(AccountName, MixedAmount)])

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

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

Apply a transform function to this transaction's amounts.

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

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

transactionToCost :: Map CommoditySymbol AmountStyle -> Transaction -> Transaction

Convert this transaction's amounts to cost, and apply the appropriate amount styles.

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

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

Apply a transformation to a transaction's postings.

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

Apply a transformation to a transaction's posting amounts.

date operations

transactionDate2 :: Transaction -> Day

transaction description parts

transactionPayee :: Transaction -> Text

transactionNote :: Transaction -> Text

rendering

showTransaction :: Transaction -> Text

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

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.

showPostingLines :: Posting -> [Text]

Render a posting, simply. Used in balance assertion errors. showPostingLine p = lineIndent $ if pstatus p == Cleared then "* " else "" ++ -- XXX show ! showAccountName Nothing (ptype p) (paccount p) ++ " " ++ showMixedAmountOneLine (pamount p) ++ assertion where -- XXX extract, handle == assertion = maybe "" ((" = " ++) . showAmountWithZeroCommodity . baamount) $ pbalanceassertion p

Render a posting, at the appropriate width for aligning with its siblings if any. Used by the rewrite command.

GenericSourcePos

sourceFilePath :: GenericSourcePos -> FilePath

sourceFirstLine :: GenericSourcePos -> Int

showGenericSourcePos :: GenericSourcePos -> String

Render source position in human-readable form. Keep in sync with Hledger.UI.ErrorScreen.hledgerparseerrorpositionp (temporary). XXX

annotateErrorWithTransaction :: Transaction -> String -> String

transactionFile :: Transaction -> FilePath

The file path from which this transaction was parsed.

tests

tests_Transaction :: TestTree