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

Safe Haskell | None
Language | Haskell2010

Hledger.Data.Valuation

Description

Convert amounts to some related value in various ways. This involves looking up historical market prices (exchange rates) between commodities.

Synopsis

- data ConversionOp
  - = NoConversionOp
  - | ToCost
- data ValuationType
  - = AtThen (Maybe CommoditySymbol)
  - | AtEnd (Maybe CommoditySymbol)
  - | AtNow (Maybe CommoditySymbol)
  - | AtDate Day (Maybe CommoditySymbol)
- type PriceOracle = (Day, CommoditySymbol, Maybe CommoditySymbol) -> Maybe (CommoditySymbol, Quantity)
- journalPriceOracle :: Bool -> Journal -> PriceOracle
- mixedAmountToCost :: Map CommoditySymbol AmountStyle -> ConversionOp -> MixedAmount -> MixedAmount
- mixedAmountApplyValuation :: PriceOracle -> Map CommoditySymbol AmountStyle -> Day -> Day -> Day -> ValuationType -> MixedAmount -> MixedAmount
- mixedAmountValueAtDate :: PriceOracle -> Map CommoditySymbol AmountStyle -> Maybe CommoditySymbol -> Day -> MixedAmount -> MixedAmount
- mixedAmountApplyGain :: PriceOracle -> Map CommoditySymbol AmountStyle -> Day -> Day -> Day -> ValuationType -> MixedAmount -> MixedAmount
- mixedAmountGainAtDate :: PriceOracle -> Map CommoditySymbol AmountStyle -> Maybe CommoditySymbol -> Day -> MixedAmount -> MixedAmount
- marketPriceReverse :: MarketPrice -> MarketPrice
- priceDirectiveToMarketPrice :: PriceDirective -> MarketPrice
- amountPriceDirectiveFromCost :: Day -> Amount -> Maybe PriceDirective
- valuationTypeValuationCommodity :: ValuationType -> Maybe CommoditySymbol
- tests_Valuation :: TestTree

# Documentation

data ConversionOp #

Which operation to perform on conversion transactions. (There was also an "infer equity postings" operation, but that is now done earlier, in journal finalisation.)

Constructors

NoConversionOp |
ToCost |

#### Instances

Instances details

Show ConversionOp # |
Instance details Defined in Hledger.Data.Valuation Methods showsPrec :: Int -> ConversionOp -> ShowS # show :: ConversionOp -> String # showList :: [ConversionOp] -> ShowS #
Eq ConversionOp # |
Instance details Defined in Hledger.Data.Valuation Methods (==) :: ConversionOp -> ConversionOp -> Bool # (/=) :: ConversionOp -> ConversionOp -> Bool #

data ValuationType #

What kind of value conversion should be done on amounts ? CLI: --value=then|end|now|DATE[,COMM]

Constructors

AtThen (Maybe CommoditySymbol) | convert to default or given valuation commodity, using market prices at each posting's date
AtEnd (Maybe CommoditySymbol) | convert to default or given valuation commodity, using market prices at period end(s)
AtNow (Maybe CommoditySymbol) | convert to default or given valuation commodity, using current market prices
AtDate Day (Maybe CommoditySymbol) | convert to default or given valuation commodity, using market prices on some date

#### Instances

Instances details

Show ValuationType # |
Instance details Defined in Hledger.Data.Valuation Methods showsPrec :: Int -> ValuationType -> ShowS # show :: ValuationType -> String # showList :: [ValuationType] -> ShowS #
Eq ValuationType # |
Instance details Defined in Hledger.Data.Valuation Methods (==) :: ValuationType -> ValuationType -> Bool # (/=) :: ValuationType -> ValuationType -> Bool #

type PriceOracle = (Day, CommoditySymbol, Maybe CommoditySymbol) -> Maybe (CommoditySymbol, Quantity) #

A price oracle is a magic memoising function that efficiently looks up market prices (exchange rates) from one commodity to another (or if unspecified, to a default valuation commodity) on a given date.

journalPriceOracle :: Bool -> Journal -> PriceOracle #

Generate a price oracle (memoising price lookup function) from a journal's directive-declared and transaction-inferred market prices. For best performance, generate this only once per journal, reusing it across reports if there are more than one, as compoundBalanceCommand does. The boolean argument is whether to infer market prices from transactions or not.

mixedAmountToCost :: Map CommoditySymbol AmountStyle -> ConversionOp -> MixedAmount -> MixedAmount #

Convert all component amounts to cost/selling price if requested, and style them.

mixedAmountApplyValuation :: PriceOracle -> Map CommoditySymbol AmountStyle -> Day -> Day -> Day -> ValuationType -> MixedAmount -> MixedAmount #

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

mixedAmountValueAtDate :: PriceOracle -> Map CommoditySymbol AmountStyle -> Maybe CommoditySymbol -> Day -> MixedAmount -> MixedAmount #

Find the market value of each component amount in the given commodity, or its default valuation commodity, at the given valuation date, using the given market price oracle. When market prices available on that date are not sufficient to calculate the value, amounts are left unchanged.

mixedAmountApplyGain :: PriceOracle -> Map CommoditySymbol AmountStyle -> Day -> Day -> Day -> ValuationType -> MixedAmount -> MixedAmount #

Calculate the gain of each component amount, that is the difference between the valued amount and the value of the cost basis (see mixedAmountApplyValuation).

If the commodity we are valuing in is not the same as the commodity of the cost, this will value the cost at the same date as the primary amount. This may not be what you want; for example you may want the cost valued at the posting date. If so, let us know and we can change this behaviour.

mixedAmountGainAtDate :: PriceOracle -> Map CommoditySymbol AmountStyle -> Maybe CommoditySymbol -> Day -> MixedAmount -> MixedAmount #

Calculate the gain of each component amount, that is the difference between the valued amount and the value of the cost basis.

If the commodity we are valuing in is not the same as the commodity of the cost, this will value the cost at the same date as the primary amount. This may not be what you want; for example you may want the cost valued at the posting date. If so, let us know and we can change this behaviour.

marketPriceReverse :: MarketPrice -> MarketPrice #

priceDirectiveToMarketPrice :: PriceDirective -> MarketPrice #

amountPriceDirectiveFromCost :: Day -> Amount -> Maybe PriceDirective #

Infer a market price from the given amount and its cost (if any), and make a corresponding price directive on the given date. The price's display precision will be set to show all significant decimal digits; or if they seem to be infinite, defaultPrecisionLimit.

valuationTypeValuationCommodity :: ValuationType -> Maybe CommoditySymbol #

tests_Valuation :: TestTree #