hledger-lib-1.30: A reusable library providing the core functionality of hledger

Safe Haskell | Safe-Inferred
Language | Haskell2010

Hledger.Data.Posting

Contents

- Posting
- operations
- date operations
- account name operations
- comment/tag operations
- arithmetic
- rendering
- misc.

Description

A `Posting` represents a change (by some `MixedAmount`) of the balance in some `Account`. Each `Transaction` contains two or more postings which should add up to 0. Postings reference their parent transaction, so we can look up the date or description there.

Synopsis

- nullposting :: Posting
- posting :: Posting
- post :: AccountName -> Amount -> Posting
- vpost :: AccountName -> Amount -> Posting
- post' :: AccountName -> Amount -> Maybe BalanceAssertion -> Posting
- vpost' :: AccountName -> Amount -> Maybe BalanceAssertion -> Posting
- nullsourcepos :: (SourcePos, SourcePos)
- nullassertion :: BalanceAssertion
- balassert :: Amount -> Maybe BalanceAssertion
- balassertTot :: Amount -> Maybe BalanceAssertion
- balassertParInc :: Amount -> Maybe BalanceAssertion
- balassertTotInc :: Amount -> Maybe BalanceAssertion
- originalPosting :: Posting -> Posting
- postingStatus :: Posting -> Status
- isReal :: Posting -> Bool
- isVirtual :: Posting -> Bool
- isBalancedVirtual :: Posting -> Bool
- isEmptyPosting :: Posting -> Bool
- hasBalanceAssignment :: Posting -> Bool
- hasAmount :: Posting -> Bool
- postingAllTags :: Posting -> [Tag]
- transactionAllTags :: Transaction -> [Tag]
- relatedPostings :: Posting -> [Posting]
- postingStripPrices :: Posting -> Posting
- postingApplyAliases :: [AccountAlias] -> Posting -> Either RegexError Posting
- postingApplyCommodityStyles :: Map CommoditySymbol AmountStyle -> Posting -> Posting
- postingAddTags :: Posting -> [Tag] -> Posting
- postingDate :: Posting -> Day
- postingDate2 :: Posting -> Day
- postingDateOrDate2 :: WhichDate -> Posting -> Day
- isPostingInDateSpan :: DateSpan -> Posting -> Bool
- isPostingInDateSpan' :: WhichDate -> DateSpan -> Posting -> Bool
- accountNamesFromPostings :: [Posting] -> [AccountName]
- commentJoin :: Text -> Text -> Text
- commentAddTag :: Text -> Tag -> Text
- commentAddTagNextLine :: Text -> Tag -> Text
- sumPostings :: [Posting] -> MixedAmount
- showPosting :: Posting -> String
- showPostingLines :: Posting -> [Text]
- postingAsLines :: Bool -> Bool -> Int -> Int -> Posting -> ([Text], Int, Int)
- postingsAsLines :: Bool -> [Posting] -> [Text]
- showAccountName :: Maybe Int -> PostingType -> AccountName -> Text
- renderCommentLines :: Text -> [Text]
- showBalanceAssertion :: BalanceAssertion -> WideBuilder
- postingTransformAmount :: (MixedAmount -> MixedAmount) -> Posting -> Posting
- postingApplyValuation :: PriceOracle -> Map CommoditySymbol AmountStyle -> Day -> Day -> ValuationType -> Posting -> Posting
- postingToCost :: Map CommoditySymbol AmountStyle -> ConversionOp -> Posting -> Maybe Posting
- postingAddInferredEquityPostings :: Bool -> Text -> Posting -> [Posting]
- postingPriceDirectivesFromCost :: Posting -> [PriceDirective]
- tests_Posting :: TestTree

# Posting

nullposting :: Posting Source #

posting :: Posting Source #

post :: AccountName -> Amount -> Posting Source #

Make a posting to an account.

vpost :: AccountName -> Amount -> Posting Source #

Make a virtual (unbalanced) posting to an account.

post' :: AccountName -> Amount -> Maybe BalanceAssertion -> Posting Source #

Make a posting to an account, maybe with a balance assertion.

vpost' :: AccountName -> Amount -> Maybe BalanceAssertion -> Posting Source #

Make a virtual (unbalanced) posting to an account, maybe with a balance assertion.

nullsourcepos :: (SourcePos, SourcePos) Source #

nullassertion :: BalanceAssertion Source #

balassert :: Amount -> Maybe BalanceAssertion Source #

Make a partial, exclusive balance assertion.

balassertTot :: Amount -> Maybe BalanceAssertion Source #

Make a total, exclusive balance assertion.

balassertParInc :: Amount -> Maybe BalanceAssertion Source #

Make a partial, inclusive balance assertion.

balassertTotInc :: Amount -> Maybe BalanceAssertion Source #

Make a total, inclusive balance assertion.

# operations

originalPosting :: Posting -> Posting Source #

postingStatus :: Posting -> Status Source #

Get a posting's status. This is cleared or pending if those are explicitly set on the posting, otherwise the status of its parent transaction, or unmarked if there is no parent transaction. (Note the ambiguity, unmarked can mean "posting and transaction are both unmarked" or "posting is unmarked and don't know about the transaction".

isReal :: Posting -> Bool Source #

isVirtual :: Posting -> Bool Source #

isBalancedVirtual :: Posting -> Bool Source #

isEmptyPosting :: Posting -> Bool Source #

hasBalanceAssignment :: Posting -> Bool Source #

hasAmount :: Posting -> Bool Source #

postingAllTags :: Posting -> [Tag] Source #

Tags for this posting including any inherited from its parent transaction.

transactionAllTags :: Transaction -> [Tag] Source #

Tags for this transaction including any from its postings.

relatedPostings :: Posting -> [Posting] Source #

postingStripPrices :: Posting -> Posting Source #

Strip all prices from a Posting.

postingApplyAliases :: [AccountAlias] -> Posting -> Either RegexError Posting Source #

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

postingApplyCommodityStyles :: Map CommoditySymbol AmountStyle -> Posting -> Posting Source #

Choose and apply a consistent display style to the posting amounts in each commodity (see journalCommodityStyles).

postingAddTags :: Posting -> [Tag] -> Posting Source #

Add tags to a posting, discarding any for which the posting already has a value.

# date operations

postingDate :: Posting -> Day Source #

Get a posting's (primary) date - it's own primary date if specified, otherwise the parent transaction's primary date, or the null date if there is no parent transaction.

postingDate2 :: Posting -> Day Source #

Get a posting's secondary (secondary) date, which is the first of: posting's secondary date, transaction's secondary date, posting's primary date, transaction's primary date, or the null date if there is no parent transaction.

postingDateOrDate2 :: WhichDate -> Posting -> Day Source #

Get a posting's primary or secondary date, as specified.

isPostingInDateSpan :: DateSpan -> Posting -> Bool Source #

Does this posting fall within the given date span ?

isPostingInDateSpan' :: WhichDate -> DateSpan -> Posting -> Bool Source #

# account name operations

accountNamesFromPostings :: [Posting] -> [AccountName] Source #

Sorted unique account names referenced by these postings.

# comment/tag operations

commentJoin :: Text -> Text -> Text Source #

Join two parts of a comment, eg a tag and another tag, or a tag and a non-tag, on a single line. Interpolates a comma and space unless one of the parts is empty.

commentAddTag :: Text -> Tag -> Text Source #

Add a tag to a comment, comma-separated from any prior content. A space is inserted following the colon, before the value.

commentAddTagNextLine :: Text -> Tag -> Text Source #

Add a tag on its own line to a comment, preserving any prior content. A space is inserted following the colon, before the value.

# arithmetic

sumPostings :: [Posting] -> MixedAmount Source #

Sum all amounts from a list of postings.

# rendering

showPosting :: Posting -> String Source #

showPostingLines :: Posting -> [Text] Source #

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

postingAsLines :: Bool -> Bool -> Int -> Int -> Posting -> ([Text], Int, Int) Source #

Render one posting, on one or more lines, suitable for `print` output. There will be an indented account name, plus one or more of status flag, posting amount, balance assertion, same-line comment, next-line comments.

If the posting's amount is implicit or if elideamount is true, no amount is shown.

If the posting's amount is explicit and multi-commodity, multiple similar postings are shown, one for each commodity, to help produce parseable journal syntax. Or if onelineamounts is true, such amounts are shown on one line, comma-separated (and the output will not be valid journal syntax).

By default, 4 spaces (2 if there's a status flag) are shown between account name and start of amount area, which is typically 12 chars wide and contains a right-aligned amount (so 10-12 visible spaces between account name and amount is typical). When given a list of postings to be aligned with, the whitespace will be increased if needed to match the posting with the longest account name. This is used to align the amounts of a transaction's postings.

Also returns the account width and amount width used.

postingsAsLines :: Bool -> [Posting] -> [Text] Source #

Given a transaction and its postings, render the postings, suitable for `print` output. Normally this output will be valid journal syntax which hledger can reparse (though it may include no-longer-valid balance assertions).

Explicit amounts are shown, any implicit amounts are not.

Postings with multicommodity explicit amounts are handled as follows: if onelineamounts is true, these amounts are shown on one line, comma-separated, and the output will not be valid journal syntax. Otherwise, they are shown as several similar postings, one per commodity. When the posting has a balance assertion, it is attached to the last of these postings.

The output will appear to be a balanced transaction. Amounts' display precisions, which may have been limited by commodity directives, will be increased if necessary to ensure this.

Posting amounts will be aligned with each other, starting about 4 columns beyond the widest account name (see postingAsLines for details).

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

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

renderCommentLines :: Text -> [Text] Source #

Render a transaction or posting's comment as indented, semicolon-prefixed comment lines. The first line (unless empty) will have leading space, subsequent lines will have a larger indent.

showBalanceAssertion :: BalanceAssertion -> WideBuilder Source #

Render a balance assertion, as the =[=][*] symbol and expected amount.

# misc.

postingTransformAmount :: (MixedAmount -> MixedAmount) -> Posting -> Posting Source #

Apply a transform function to this posting's amount.

postingApplyValuation :: PriceOracle -> Map CommoditySymbol AmountStyle -> Day -> Day -> ValuationType -> Posting -> Posting Source #

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

postingToCost :: Map CommoditySymbol AmountStyle -> ConversionOp -> Posting -> Maybe Posting Source #

Maybe convert this `Posting`s amount to cost, and apply apply appropriate amount styles.

postingAddInferredEquityPostings :: Bool -> Text -> Posting -> [Posting] Source #

Generate inferred equity postings from a `Posting` using transaction prices. Make sure not to generate equity postings when there are already matched conversion postings.

postingPriceDirectivesFromCost :: Posting -> [PriceDirective] Source #

Make a market price equivalent to this posting's amount's unit price, if any.

tests_Posting :: TestTree Source #