Hledger.Data.Posting

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.

Posting

nullposting :: Posting

posting :: Posting

post :: AccountName -> Amount -> Posting

Make a posting to an account.

vpost :: AccountName -> Amount -> Posting

Make a virtual (unbalanced) posting to an account.

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

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

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

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

nullassertion :: BalanceAssertion

balassert :: Amount -> Maybe BalanceAssertion

Make a partial, exclusive balance assertion.

balassertTot :: Amount -> Maybe BalanceAssertion

Make a total, exclusive balance assertion.

balassertParInc :: Amount -> Maybe BalanceAssertion

Make a partial, inclusive balance assertion.

balassertTotInc :: Amount -> Maybe BalanceAssertion

Make a total, inclusive balance assertion.

operations

originalPosting :: Posting -> Posting

postingStatus :: Posting -> Status

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

isVirtual :: Posting -> Bool

isBalancedVirtual :: Posting -> Bool

isEmptyPosting :: Posting -> Bool

hasBalanceAssignment :: Posting -> Bool

hasAmount :: Posting -> Bool

postingAllTags :: Posting -> [Tag]

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

transactionAllTags :: Transaction -> [Tag]

Tags for this transaction including any from its postings.

relatedPostings :: Posting -> [Posting]

postingStripCosts :: Posting -> Posting

Strip all prices from a Posting.

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

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

Deprecated: please use styleAmounts instead

Find and apply the appropriate display style to the posting amounts in each commodity (see journalCommodityStyles). Main amount precisions may be set or not according to the styles, but cost precisions are not set.

postingStyleAmounts :: Map CommoditySymbol AmountStyle -> Posting -> Posting

Deprecated: please use styleAmounts instead

Like postingApplyCommodityStyles, but neither main amount precisions or cost precisions are set.

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

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

postingAddHiddenAndMaybeVisibleTag :: Bool -> HiddenTag -> Posting -> Posting

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

date operations

postingDate :: Posting -> Day

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

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

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

isPostingInDateSpan :: DateSpan -> Posting -> Bool

Does this posting fall within the given date span ?

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

account name operations

accountNamesFromPostings :: [Posting] -> [AccountName]

Sorted unique account names referenced by these postings.

comment/tag operations

commentJoin :: Text -> Text -> Text

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

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

commentAddTagUnspaced :: Text -> Tag -> Text

Like commentAddTag, but omits the space after the colon.

commentAddTagNextLine :: Text -> Tag -> Text

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

generatedTransactionTagName :: TagName

Special tags hledger sometimes adds to mark various things. These should be hidden tag names, beginning with _. With --verbose-tags, the equivalent visible tags will also be added. These tag names are mentioned in docs and can be matched by user queries, so consider the impact before changing them.

modifiedTransactionTagName :: TagName

Special tags hledger sometimes adds to mark various things. These should be hidden tag names, beginning with _. With --verbose-tags, the equivalent visible tags will also be added. These tag names are mentioned in docs and can be matched by user queries, so consider the impact before changing them.

generatedPostingTagName :: TagName

Special tags hledger sometimes adds to mark various things. These should be hidden tag names, beginning with _. With --verbose-tags, the equivalent visible tags will also be added. These tag names are mentioned in docs and can be matched by user queries, so consider the impact before changing them.

costPostingTagName :: TagName

Special tags hledger sometimes adds to mark various things. These should be hidden tag names, beginning with _. With --verbose-tags, the equivalent visible tags will also be added. These tag names are mentioned in docs and can be matched by user queries, so consider the impact before changing them.

conversionPostingTagName :: TagName

Special tags hledger sometimes adds to mark various things. These should be hidden tag names, beginning with _. With --verbose-tags, the equivalent visible tags will also be added. These tag names are mentioned in docs and can be matched by user queries, so consider the impact before changing them.

arithmetic

sumPostings :: [Posting] -> MixedAmount

Sum all amounts from a list of postings.

negatePostingAmount :: Posting -> Posting

Negate amount in a posting.

rendering

showPosting :: Posting -> String

showPostingLines :: Posting -> [Text]

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)

Render one posting, on one or more lines, suitable for print output. Also returns the widths calculated for the account and amount fields.

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

If an amount is zero, any commodity symbol attached to it is shown (and the corresponding commodity display style is used).

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.

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

Render a transaction's postings as indented lines, suitable for print output.

Normally these will be in valid journal syntax which hledger can reparse (though they may include no-longer-valid balance assertions). Explicit amounts are shown, 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.

Posting amounts will be aligned with each other, starting about 4 columns beyond the widest account name (see postingAsLines for details). The postings will appear balanced (amounts summing to zero). Amounts' display precisions, which may have been limited by commodity directives, will be increased if necessary to ensure this.

postingIndent :: Text -> Text

Prepend a suitable indent for a posting (or transaction/posting comment) line.

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.

renderCommentLines :: Text -> [Text]

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

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

misc.

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

Apply a transform function to this posting's amount.

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

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

postingToCost :: ConversionOp -> Posting -> Maybe Posting

Maybe convert this Postings amount to cost.

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

Generate equity conversion postings corresponding to a Posting's cost(s) (one pair of conversion postings per cost), wherever they don't already exist.

postingPriceDirectivesFromCost :: Posting -> [PriceDirective]

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

tests_Posting :: TestTree

Orphan instances

HasAmounts BalanceAssertion

Methods

styleAmounts :: Map CommoditySymbol AmountStyle -> BalanceAssertion -> BalanceAssertion

HasAmounts Posting

Methods

styleAmounts :: Map CommoditySymbol AmountStyle -> Posting -> Posting