lib: Hledger.Utils.Debug: lbl_ helper, cleanups, notes

hledger-lib/Hledger/Utils/Debug.hs

@@ -64,10 +64,27 @@ Debug level:  What to show:
 9             any other rarely needed / more in-depth info
 @
 
+We don't yet have the ability to select debug output by topic. For now, here
+are some standardish topic strings to search for in hledger debug messages:
+
+acct
+arg
+budget
+calc
+csv
+journalFinalise
+multiBalanceReport
+opts
+precision
+price
+q
+style
+val
+
 -}
 
--- Disabled until 0.1.2.0 is released with windows support
+-- Disabled until 0.1.2.0 is released with windows support:
--- This module also exports Debug.Trace and the breakpoint package's Debug.Breakpoint.
+--  This module also exports Debug.Trace and the breakpoint package's Debug.Breakpoint.
 
 -- more:
 -- http://hackage.haskell.org/packages/archive/TraceUtils/0.1.0.2/doc/html/Debug-TraceUtils.html
@@ -75,6 +92,7 @@ Debug level:  What to show:
 -- http://hackage.haskell.org/packages/archive/htrace/0.1/doc/html/Debug-HTrace.html
 -- http://hackage.haskell.org/packages/archive/traced/2009.7.20/doc/html/Debug-Traced.html
 -- https://hackage.haskell.org/package/debug
+{-# OPTIONS_GHC -Wno-unrecognised-pragmas #-}
 
 module Hledger.Utils.Debug (
 
@@ -142,6 +160,9 @@ module Hledger.Utils.Debug (
   ,dbg8With
   ,dbg9With
 
+  -- * Utilities
+  ,lbl_
+
   -- * Re-exports
   -- ,module Debug.Breakpoint
   ,module Debug.Trace
@@ -433,3 +454,25 @@ dbg8With = traceOrLogAtWith 8
 dbg9With :: Show a => (a -> String) -> a -> a
 dbg9With = traceOrLogAtWith 9
 
+-- | Helper for producing debug messages:
+-- concatenates a name (eg a function name),
+-- short description of the value being logged,
+-- and string representation of the value.
+lbl_ :: String -> String -> String -> String
+lbl_ name desc val = name <> ": " <> desc <> ":" <> " " <> val
+
+-- XXX the resulting function is constrained to only one value type
+-- -- | A new helper for defining a local "dbg" function.
+-- -- Given a debug level and a topic string (eg, a function name),
+-- -- it generates a function which takes
+-- -- - a description string,
+-- -- - a value-to-string show function,
+-- -- - and a value to be inspected,
+-- -- debug-logs the topic, description and result of calling the show function on the value,
+-- -- formatted nicely, at the specified debug level or above,
+-- -- then returns the value.
+-- dbg_ :: forall a. Show a => Int -> String -> (String -> (a -> String) -> a -> a)
+-- dbg_ level topic =
+--   \desc showfn val ->
+--     traceOrLogAtWith level (lbl_ topic desc . showfn) val
+-- {-# HLINT ignore "Redundant lambda" #-}