hledger-lib-1.12: Core data types, parsers and functionality for the hledger accounting tools

Safe Haskell | None
Language | Haskell2010

Hledger.Data.Transaction

Contents

- Transaction
- operations
- date operations
- arithmetic
- rendering
- GenericSourcePos
- tests

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
- txnTieKnot :: Transaction -> Transaction
- txnUntieKnot :: Transaction -> Transaction
- showAccountName :: Maybe Int -> PostingType -> AccountName -> String
- hasRealPostings :: Transaction -> Bool
- realPostings :: Transaction -> [Posting]
- assignmentPostings :: Transaction -> [Posting]
- virtualPostings :: Transaction -> [Posting]
- balancedVirtualPostings :: Transaction -> [Posting]
- transactionsPostings :: [Transaction] -> [Posting]
- isTransactionBalanced :: Maybe (Map CommoditySymbol AmountStyle) -> Transaction -> Bool
- transactionDate2 :: Transaction -> Day
- transactionPostingBalances :: Transaction -> (MixedAmount, MixedAmount, MixedAmount)
- balanceTransaction :: Maybe (Map CommoditySymbol AmountStyle) -> Transaction -> Either String Transaction
- balanceTransactionUpdate :: MonadError String m => (AccountName -> MixedAmount -> m ()) -> Maybe (Map CommoditySymbol AmountStyle) -> Transaction -> m Transaction
- showTransaction :: Transaction -> String
- showTransactionUnelided :: Transaction -> String
- showTransactionUnelidedOneLineAmounts :: Transaction -> String
- showPostingLine :: Posting -> String
- showPostingLines :: Posting -> [String]
- sourceFilePath :: GenericSourcePos -> FilePath
- sourceFirstLine :: GenericSourcePos -> Int
- showGenericSourcePos :: GenericSourcePos -> String
- tests_Transaction :: Test ()

# Transaction

nulltransaction :: Transaction Source #

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

showAccountName :: Maybe Int -> PostingType -> AccountName -> String Source #

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

hasRealPostings :: Transaction -> Bool Source #

realPostings :: Transaction -> [Posting] Source #

assignmentPostings :: Transaction -> [Posting] Source #

virtualPostings :: Transaction -> [Posting] Source #

balancedVirtualPostings :: Transaction -> [Posting] Source #

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

isTransactionBalanced :: Maybe (Map CommoditySymbol AmountStyle) -> Transaction -> Bool Source #

Does this transaction appear balanced when rendered, optionally with the given commodity display styles ? More precisely: after converting amounts to cost using explicit transaction prices if any; and summing the real postings, and summing the balanced virtual postings; and applying the given display styles if any (maybe affecting decimal places); do both totals appear to be zero when rendered ?

# date operations

transactionDate2 :: Transaction -> Day Source #

# arithmetic

transactionPostingBalances :: Transaction -> (MixedAmount, MixedAmount, MixedAmount) Source #

Get the sums of a transaction's real, virtual, and balanced virtual postings.

balanceTransaction :: Maybe (Map CommoditySymbol AmountStyle) -> Transaction -> Either String Transaction Source #

Ensure this transaction is balanced, possibly inferring a missing amount or conversion price(s), or return an error message. Balancing is affected by commodity display precisions, so those can (optionally) be provided.

this fails for example, if there are several missing amounts (possibly with balance assignments)

balanceTransactionUpdate Source #

Arguments

:: MonadError String m |
=> (AccountName -> MixedAmount -> m ()) | update function
-> Maybe (Map CommoditySymbol AmountStyle) |
-> Transaction |
-> m Transaction |

More general version of `balanceTransaction` that takes an update function

# rendering

showTransaction :: Transaction -> String Source #

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

Ledger 2.x's standard format looks like this:

    yyyymmdd[ *][ 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).

If there are multiple postings, all with explicit amounts, and the transaction appears obviously balanced (postings sum to 0, without needing to infer conversion prices), the last posting's amount will not be shown.

showTransactionUnelided :: Transaction -> String Source #

Like showTransaction, but does not change amounts' explicitness. Explicit amounts are shown and implicit amounts are not. 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. Most often, this is the one you want to use.

showTransactionUnelidedOneLineAmounts :: Transaction -> String Source #

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

showPostingLine :: Posting -> String Source #

Show a posting's status, account name and amount on one line. Used in balance assertion errors.

showPostingLines :: Posting -> [String] Source #

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

# GenericSourcePos

sourceFilePath :: GenericSourcePos -> FilePath Source #

sourceFirstLine :: GenericSourcePos -> Int Source #

showGenericSourcePos :: GenericSourcePos -> String Source #

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

# tests

tests_Transaction :: Test () Source #