dev: cleanup; add showAmountWith, showMixedAmountWith

hledger-lib/Hledger/Data/Amount.hs

@@ -82,8 +82,9 @@ module Hledger.Data.Amount (
   noCostFmt,
   oneLineFmt,
   machineFmt,
-  showAmountB,
   showAmount,
+  showAmountWith,
+  showAmountB,
   showAmountsCostB,
   cshowAmount,
   showAmountWithZeroCommodity,
@@ -143,6 +144,7 @@ module Hledger.Data.Amount (
   mixedAmountUnstyled,
   -- ** rendering
   showMixedAmount,
+  showMixedAmountWith,
   showMixedAmountOneLine,
   showMixedAmountDebug,
   showMixedAmountWithoutCost,
@@ -214,9 +216,8 @@ quoteCommoditySymbolIfNeeded s
   | T.any isNonsimpleCommodityChar s = "\"" <> s <> "\""
   | otherwise = s
 
-
+-- | Formatting options available when displaying Amounts and MixedAmounts.
--- | Options for displaying Amounts and MixedAmounts.
+-- Similar to "AmountStyle" but lower level, and not attached to amounts or commodities.
--- Similar to "AmountStyle" but lower level.
 -- See also hledger manual > "Amount formatting, parseability", which speaks of human, hledger, and machine output.
 data AmountFormat = AmountFormat
   { displayCommodity        :: Bool       -- ^ Whether to display commodity symbols.
@@ -631,27 +632,19 @@ showAmountCostDebug Nothing                = ""
 showAmountCostDebug (Just (UnitCost pa))  = " @ "  ++ showAmountDebug pa
 showAmountCostDebug (Just (TotalCost pa)) = " @@ " ++ showAmountDebug pa
 
--- | Get the string representation of an amount, based on its
+-- | Render an amount using its display style and the default amount format.
--- commodity's display settings. String representations equivalent to
+-- Zero-equivalent amounts  are shown as just \"0\".
--- zero are converted to just \"0\". The special "missing" amount is
+-- The special "missing" amount is shown as the empty string.
--- displayed as the empty string.
---
--- > showAmount = wbUnpack . showAmountB defaultFmt
 showAmount :: Amount -> String
 showAmount = wbUnpack . showAmountB defaultFmt
 
--- | General function to generate a WideBuilder for an Amount, according the
+-- | Like showAmount but uses the given amount format.
--- supplied AmountFormat. This is the main function to use for showing
+showAmountWith :: AmountFormat -> Amount -> String
--- Amounts, constructing a builder; it can then be converted to a Text with
+showAmountWith fmt = wbUnpack . showAmountB fmt
--- wbToText, or to a String with wbUnpack.
+
--- Some special cases:
+-- | Render an amount using its display style and the given amount format, as a builder for efficiency.
---
+-- (This can be converted to a Text with wbToText or to a String with wbUnpack).
--- * The special "missing" amount is displayed as the empty string. 
+-- The special "missing" amount is displayed as the empty string. 
---
--- * If an amount is showing digit group separators but no decimal places,
---   we force showing a decimal mark (with nothing after it) to make
---   it easier to parse correctly.
---
 showAmountB :: AmountFormat -> Amount -> WideBuilder
 showAmountB _ Amount{acommodity="AUTO"} = mempty
 showAmountB
@@ -1031,9 +1024,13 @@ mixedAmountUnstyled = mapMixedAmountUnsafe amountUnstyled
 showMixedAmount :: MixedAmount -> String
 showMixedAmount = wbUnpack . showMixedAmountB defaultFmt
 
+-- | Like showMixedAmount but uses the given amount format.
+-- See showMixedAmountB for special cases.
+showMixedAmountWith :: AmountFormat -> MixedAmount -> String
+showMixedAmountWith fmt = wbUnpack . showMixedAmountB fmt
+
 -- | Get the one-line string representation of a mixed amount (also showing any costs).
---
+-- See showMixedAmountB for special cases.
--- > showMixedAmountOneLine = wbUnpack . showMixedAmountB oneLineFmt
 showMixedAmountOneLine :: MixedAmount -> String
 showMixedAmountOneLine = wbUnpack . showMixedAmountB oneLineFmt{displayCost=True}
 

hledger-lib/Hledger/Data/Types.hs

@@ -249,10 +249,13 @@ deriving instance Generic (DecimalRaw a)
 data AmountCost = UnitCost !Amount | TotalCost !Amount
   deriving (Eq,Ord,Generic,Show)
 
--- | Every Amount has one of these, influencing how the amount is displayed.
+-- | Display styles for amounts - things which can be detected during parsing, such as
--- Also each Commodity has one, inferred from the corresponding amounts, directives and options,
+-- commodity side and spacing, digit group marks, decimal mark, number of decimal digits etc.
--- then applied to all of its amounts for consistent display.
+-- Every "Amount" has an AmountStyle.
--- Similar to "AmountFormat" but higher level.
+-- After amounts are parsed from the input, for each "Commodity" a standard style is inferred
+-- and then used when displaying amounts in that commodity.
+-- Related to "AmountFormat" but higher level.
+--
 -- See also:
 -- - hledger manual > Commodity styles
 -- - hledger manual > Amounts